swagger-to 1.1.1

Swagger-to

Swagger-to generates server and client code from Swagger (OpenAPI 2.0) specification; written in Python 3.

We wanted a code generator that is 1) easy to write, maintain and extend and that 2) produces readable code.

To achieve this, we wrote the tool in Python which we found to be far superior for code generation compared with other languages such as Go and Java. Since the original Swagger specification can become quite complex, we introduce an intermediate representation layer after parsing the specification and before generating the code. This layer allowed us to substantially simplify the generation code since it reduced the impedance mismatch by operating on abstract constructs (such as Maps) instead of directly referring to “raw” Swagger constructs (such as additional properties of an object).

The underlying language (Python), readable generated code and the intermediate representation layer are the two main differentiators to other similar code generation projects.

Supported languages:

Related Projects

We list here some of the related projects and comment why they did not satisfy our requirements.

• https://github.com/go-swagger/go-swagger produces code which looked a bit too clumsy for us.

• https://github.com/swagger-api/swagger-codegen written in Java and hence hard for us to extend and customize.

• https://grpc.io/ gRPC is great when remote procedure calls are all you need. However, it requires you to use HTTP 2, and we found it hard to integrate with widely-used browsers as clients.

  Additionally, streaming files was not directly supported (see https://github.com/grpc/grpc-go/issues/414).

• https://github.com/grpc-ecosystem/grpc-gateway provides a JSON gateway to gRPC. We found that it added an additional layer of complexity (especially when the number of client/server pairs grow), and preferred to have a simple solution with a single code generation tool.

• https://github.com/twitchtv/twirp a (better?) alternative if you only want to generate remote procedure calls based on JSON using protocol buffers to specify the API. It forces you to stick to its representation, though, and does not allow you to use an arbitrary Swagger specification. This is problematic when the interface is imposed on you from outside (e.g., by customers).

Installation

• Create a virtual environment:

python3 -m venv venv3

• Activate it:

source venv3/bin/activate

• Install swagger_to with pip:

pip3 install swagger_to

Usage

To generate code, you need to invoke one of the swagger_to_*.py scripts. If the generated code exists, you need to specify --force command-line argument in order to overwrite the existing files.

swagger_to_go_server.py \
    --swagger_path /some/path/swagger.yaml \
    --outdir /some/go/path/src/your-server-package

swagger_to_py_client.py \
    --swagger_path /some/path/swagger.yaml \
    --outpath /some/py/path/your_client_module.py

swagger_to_ts_angular5_client.py \
    --swagger_path /some/path/swagger.yaml \
    --outpath /some/typescript/path/your_client.ts

Development

• Check out the repository.

• In the repository root, create the virtual environment:

python3 -m venv venv3

• Activate the virtual environment:

source venv3/bin/activate

• Install the development dependencies:

pip3 install -e .[dev]

• Run precommit.py to execute pre-commit checks locally.

Versioning

We follow Semantic Versioning. The version X.Y.Z indicates:

• X is the major version (backward-incompatible),

• Y is the minor version (backward-compatible), and

• Z is the patch version (backward-compatible bug fix).