swagger-python-codegen

Python-only replacement for the open-source swagger-codegen code generator (https://github.com/swagger-api/swagger-codegen).

Copyright (c) 2022-2023 CINCH Enterprises, Ltd. and Rod Pullmann. All rights reserved.

Overview

The swagger-python-codegen code generator will generate a Python 3.x SDK code package for a RESTful API for which an OpenAPI (a.k.a. Swagger) specification has been generated. An OpenAPI specification is a JSON or YAML document -- required as a local file -- compatible with the OpenAPI Specification standard version 2.x (see https://swagger.io/specification/v2). The full OpenAPI specification file for the RESTful API is required as an input to the code generator.

The heavy lifting for swagger-codegen code generation is accomplished by use of Mustache templates (see https://mustache.github.io/mustache.5.html). The swagger-python-codegen code generator uses the Python package pystache to render Mustache templates. As currently packaged, swagger-python-codegen uses the templates distributed with a given swagger-codegen release, so has a dependency on the swagger-codegen release distribution being present somewhere in the local filesystem. This release directory or JAR file is also an input to the code generator.

swagger-python-codegen is offered as a replacement for a stock version of the open-source swagger-codegen-cli code generator in order to: a) work around various long-standing bugs, which the open-source support team has neglected to fix or even acknowledge, causing erroneous SDK code to be generated, and/or b) allow for a more streamlined SDK package to be generated, omitting various extraneous file collections not of interest to all users, and/or c) generate the SDK code in a fraction of the time as the open-source product takes.

The SDK code (and other files) generated by swagger-python-codegen is functionally equivalent to what is generated by the stock swagger-codegen-cli, except with erroneous SDK code and document misformatting having been corrected.

Installation

1. Clone this repo somewhere in your local filesystem.

2. Use pip to install the application:

   $ pip3 install -e swagger-python-codegen 

   After successful installation, the generator will be available via the command swagger-python-codegen

3. Make sure that the desired swagger-codegen-cli release from the version 3.x series is downloaded to the same local filesystem; see https://repo1.maven.org/maven2/io/swagger/codegen/v3/swagger-codegen-cli for the full release tree.

   For example, to install version 3.0.35, do:

   $ export URL=https://repo1.maven.org/maven2/io/swagger/codegen/v3/swagger-codegen-cli 
   $ wget $URL/3.0.35/swagger-codegen-cli-3.0.35.jar

4. Ensure that this JAR file is "installed" somewhere accessible to swagger-python-codegen; by default, this is in /opt/swagger-codegen. Note that the stock swagger-codegen-cli code generator can be run directly from this JAR file via:

   $ java -jar /opt/swagger-codegen/swagger-codegen-cli-3.0.35.jar ... options

   Alternatively, as swagger-python-codegen functionally replaces that stock code generator, then to save space the python subdirectory contained in that JAR file can be unzipped into a filesystem directory tree somewhere, and the JAR file itself eliminated.

Usage

Run the generate.py script contained here to generate an SDK from a provided OpenAPI specification file and set of swagger-codegen Mustache templates. The command-line options supported by generate.py are compatible with those defined by swagger-codegen-cli, as are the configuration settings defined; use the --help or -h option to see a full list of options and configuration settings available for customization.

The input OpenAPI specification file path is specified by --input-spec. Only YAML and JSON files are supported, and if the PyYAML Python package is not installed locally, then only JSON is supported.

The filesystem location of the Mustache templates is specified by --template-dir; note that because options are named to be backward-compatible with swagger-codegen-cli, this option can denote the JAR file containing the templates (even though the option is the misnomer '...-dir').

Consult the other command-line options available to customize the SDK code generation process and naming. Options typically specified for most APIs are:

Option	Description
--output	Output directory tree for generated SDK Python package
--api-package	Name of the Python subpackage containing the SDK's API modules
-D packageName	Overall package name for the SDK -- what is pip-installed
-D projectName	Project title for the enclosing Python installation tree

Example command-line:

$ swagger-python-codegen -i my_api.yaml -o ./repo \
  -D packageName=sdk projectName=my_api --api-package groups

This will generate a Python installable package tree to the repo subdirectory as the topmost directory tree; the Python installer script, requirements file, and so forth reside directly in this tree, as follows:

• SDK support and configuration code is emitted to repo/sdk directory
• the importable API resource SDK modules are emitted to repo/sdk/groups
• any object model definitions are emitted to repo/sdk/models
• any other optional file collections generated by specifying the --generate option are emitted to corresponding subdirectories of repo/sdk

The full package installation tree is known as my_api. Once this package tree is pip-installed, the full SDK can then be imported by Python code via: from my_api.sdk.groups import *

Supplemental Features

By default, swagger-python-codegen will only generate the SDK code modules for the API methods themselves and any models defined publicly. Refer to the --generate command-line option for how to generate the full complement of other files (e.g., documents, unit test skeletons, etc.) thet swagger-codegen-cli does.

Refer also to the --fix option for other cleanups, fixups, and remedies to optionally be applied during code generation.