Openapi

Automatically generating OpenApi specification and Javascript client

I first heard of OpenApi from a co-worker at Periscope in 2016. I was hosting an intern, and his project was to create a CLI to make it easy for the dev team to interact with Periscope’s REST API. A stretch goal was to automatically generate API documentation.

One of the engineers in the Android team posed the question: why not use Swagger? I took a quick look at Swagger (which eventually became OpenApi) and it seemed like a good idea to adopt it, but we never did.

When I started thinking about space-api, I gave myself the mission to learn and use OpenApi. It’s definitely more work upfront, but it should pay off since it would make it trivial to automatically generate API clients, stubs for testing, and documentation.

This is how I got started. Using protoc version libprotoc 3.6.1 I generated the OpenApi specification for the service, based on the proto file.

protoc proto/unary.proto -I. --openapi_out=proto/

You can see what the automatically generated spec looks like below.

OpenApi Generator is one of the key tools in the OpenApi ecosystem. Using openapi-generator-cli version 5.3.1 and command line below, I created a javascript client for space-api, which can easily be imported via npm.

openapi-generator-cli generate -i openapi.yaml -g javascript -o .

The generated code is available at https://github.com/thiagorobert/space-client-js.

Next steps on this are to publish this package to the npm registry (instructions) and use the package on the UI code I covered before.