swagger-to 4.0.0

Missing Features

Due to the lack of time, we can not cover all of the Swagger specification. The current generators work well for all of our simple and not-so-simple use cases. We believe they can also cover most of the other people’s needs as well.

Here is a non-comprehensive list:

• anonymous objects. We do not support anonymous objects in the definitions. Please define all objects as top level definitions.

• parameters. Go server and Python client support query, body, path and header parameters. Elm and Typescript + Angular clients support only query, body and path parameters. Cookie parameters are not supported.

• default values. We do not support default values due to the impedance mismatch between JSON and the target languages.

• validation of responses. Responses from the server are not validated due to the complexity and the run-time overhead.

Elm Client

To generate an Elm client from a Swagger specification at /some/path/swagger.yaml, invoke:

swagger_to_elm_client.py \
    --swagger_path /some/path/swagger.yaml \
    --outdir /some/elm/path/src/your-client-directory

The generated code will have the following structure in /some/elm/path/src/your-client-directory:

Two non-standard libraries are used in the Client:

• “NoRedInk/elm-decode-pipeline” is used to decode JSON objects in a more scalable way than the one supported by the elm-lang libraries; and

• “elm-community/json-extra” is needed to encode Dict variables.

We use Elm’s built-in Int type to represent both 32 and 64-bit integers. Please be careful: Elm depends on JavaScript which uses solely double-precision floats both for integers and for floating-point numbers, which can lead to unexpected truncation.

Go Server

To generate a Go server from a Swagger specification at /some/path/swagger.yaml, invoke:

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

The generated code will have the following structure in /some/go/path/src/your-server-package:

All the types defined in the Swagger are translated to types.go. The routing and validation code around the endpoints is generated in jsonschemas.go and routes.go.

The handler interface is given in handler.go. You need to implement the handler logic yourself. You can use handler_impl.sample.go as a starting point. We usually just copy/paste it to handler_impl.go and ignore handler_impl.sample.go in our repositories (e.g., by adding it to .gitignore).

In face of Swagger (i.e. API) changes, our workflow includes regenerating the code and using a diff tool like meld to sync the “old” handler_impl.go with the new handler_impl.sample.go.

Python Client

To generate a Python 3 client from a Swagger specification at /some/path/swagger.yaml, invoke:

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

The generated client uses requests library.

Since input checks need to be performed by the server anyhow, we decided not to keep the code generator simple and more maintainable by including only the rudimentary type checks on the inputs. Hence all the sophisticated checks such as string patterns or casting of a Python integer to int32 are deliberately excluded. Analogously, we also do not validate the output coming from the server.

If time ever permits, we would like to include both more fine-grained input and output validation. At the moment, we did not confront any problems in the development process.

Typescript+Angular Client

To generate a Python client from a Swagger specification at /some/path/swagger.yaml, invoke:

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

The generated client uses Angular http library. For the same reasons as for Python client, no checks are performed neither on the input nor on the output.

We use Typescript’s built-in number type to represent both 32 and 64-bit integers. Please be careful: Typescript depends on JavaScript which uses solely double-precision floats both for integers and for floating-point numbers, which can lead to unexpected truncation.

Style Check

We found it important to have a uniform documentation style across all the Swagger specifications in an organization. To that end, swagger_to includes an utility to automatically check the style such as casing of the definition names, property names, descriptions and verb moods (present tense instead of imperative).To check the compliance of a Swagger specification at /some/path/swagger.yaml to the Swagger style guides, invoke:

swagger_style.py \
    --swagger_path /some/path/swagger.yaml

The following checks are performed:

• The Swagger name is in camel case, its description capitalized, and the base path starts with a slash.

• Top level type definitions are in capitalized camel case, and properties are in snake case.

• Endpoint paths, operation_id and parameter names are in camel case.

• All descriptions:

  • start with a present tense verb, whose first letter is lower case;

  • have no leading or trailing whitespaces, tabs or new lines;

  • contain either one line, or three or more, in which case the second is empty;

  • end with a period.

• Endpoint paths start with a slash, and the responses contain “200” and “default”.

The script call returns 0 in case of no violations found, 1 in case of failed checks or 2 in case of illegal usage.