Create OpenAPI Client using Docker

Generate API clients using the Swagger Code Generator  in a docker container.

This instructions were tested on a Mac, most likely will also work on a Linux host  and can easily be adapted to work on Windows.

swagger.json

Get the compatible swagger/OpenAPI API description file in the json format and save to a folder as swagger.json

For simplicity create a new folder and save the swagger.json there.

A couple helpful scripts

Create these scripts on the folder you created on the step above.

codegen-cli.sh

#!/bin/bash
docker run --rm -it \
        -w /src \
        -v "${PWD}:/gen" \
        swaggerapi/swagger-codegen-cli \
        $*

build.sh

#!/bin/bash
mkdir -p src
./codegen-cli.sh generate \
    -i /gen/swagger.json -o /gen/$1 \
    -l $1 -c /gen/$1.json

Create configuration file

The generator supports several different targets. A couple examples for typescript clients are typescript-fetch and typescript-angular.

To find the available targets:

$ ./codegen-cli.sh langs

The output will be similar to:

Available languages: [ada, ada-server, akka-scala, android, apache2, apex, aspnetcore, bash, csharp, clojure, cwiki, cpprest, csharp-dotnet2, dart, elixir, elm, eiffel, erlang-client, erlang-server, finch, flash, python-flask, go, go-server, groovy, haskell-http-client, haskell, jmeter, jaxrs-cxf-client, jaxrs-cxf, java, inflector, jaxrs-cxf-cdi, jaxrs-spec, jaxrs, msf4j, java-pkmst, java-play-framework, jaxrs-resteasy-eap, jaxrs-resteasy, javascript, javascript-closure-angular, java-vertx, kotlin, lua, lumen, nancyfx, nodejs-server, objc, perl, php, powershell, pistache-server, python, qt5cpp, r, rails5, restbed, ruby, rust, rust-server, scala, scala-gatling, scala-lagom-server, scalatra, scalaz, php-silex, sinatra, slim, spring, dynamic-html, html2, html, swagger, swagger-yaml, swift4, swift3, swift, php-symfony, tizen, typescript-aurelia, typescript-angular, typescript-inversify, typescript-angularjs, typescript-fetch, typescript-jquery, typescript-node, undertow, ze-ph, kotlin-server]

The scripts above assume a json file named after the “target type” (e.g. language) exists on the same folder of the swagger.json file. 

Configure the target

To find the options available for the target (language):

$ ./codegen-cli.sh config-help -l typescript-fetch

Replace typescript-fetch with any other valid target (languages).

typescript-fetch.json (example)

For example, to generate a typescript API client to be used in a React app, create a file typescript-fetch.json:

{
    "supportsES6": true, 
    "modelPropertyNaming": "camelCase",
    "npmName": "api",
    "npmVersion": "0.0.1",
    "withInterfaces": true
}

Generate the client code

$ ./build.sh typescript-fetch

Again, you can use any of the other targets instead of typescript-fetch on the line above

You will find the generated code client on a subfolder named the ‘target’ (e.g. ‘typescript-fetch’ for the example above)

For most targets you will find a README.md file inside this subfolder with the next steps.

For typescript-fetch (react apps using typescript)

Inside the typescritp-fetch (folder generated by the steps above)

$ npm install
$ npm run build

Edit the project.json file to update the author, description, version and others and then run:

$ npm pack

You will find a tgz file with the name derived from the name and version on your project.json.