2 min read

Generating APIs and Documentation with Swagger

Featured Image

Streamlining API Documentation

Documentation is critical to API development, especially if multiple teams are building microservices and consuming each other's APIs. However, creating and keeping documentation synchronized requires extensive manual work. The only thing worse than no documentation is incorrect documentation.

Swagger at Merit

At Merit, we use Swagger to tackle this problem. Swagger is a language and set of tools designed to make developing and maintaining API documentation easier and less time-consuming. It also ensures our documentation and code remain consistent. 

By defining a specification (spec) for an API in either YAML or JSON, readable, interactive documentation and code are generated to implement and/or consume the API. 

Swagger tools:

  • generate code in many programming languages
  • generate html or text documentation
  • check the validity of a Swagger spec
  • and more

In this diagram, the team working on "Core service A" only needs to write a correct Swagger spec to support clients in numerous languages, create documentation for developers, and accommodate automated integration testing.

Defining a Swagger spec

Here is an example Swagger spec for one of the data structures in Merit's platform.

First, we define our data structure, a field kind. This is used as a generic field inside the Merit template data structure.

Here FieldKind is a composition of three other defined Swagger types:

BaseReadModel, OwnerMetadata, and FieldKindProps

BaseReadModel contains just an `id` field. OwnerMetadata describes who owns this object. FieldKindProps contains the following fields:

  • name
  • description
  • data type (string, date, email, etc.)
  • parent id (originally extended from)
  • validation rules
  • permissions

Next we can define an endpoint /v1/fields/{fieldID} which uses the FieldKind object:

This endpoint is specified to return a FieldKind corresponding to the passed-in field kind ID.

Generating Swagger API code

We generate a working API allowing an external program to access this endpoint. To generate the "go API" code, we use "go-Swagger." The generated API code is strongly typed, which ensures correct use with each data type. We execute the following command to generate data structures for the model definitions and API code.

Installing "go-Swagger," enables running the following command to generate data structures and API method definitions for the Swagger specification.

`swagger generate client --target=./gen/restapi --model-package=models`

This creates a new directory, `gen/restapi`, which contains the following: 

  • operations_client.go
  • get_field_kind_parameters.go
  • get_field_kind_responses.go

The following snippet shows an example of this code:

We obtain a directory `gen/models`, containing model definitions used by all endpoints. Any definitions not used by an endpoint are omitted from the generated code.

This code contains the following:

  • data structure definitions
  • validation
  • serialization code

The following block illustrates how this client code might be used:

Generating interactive documentation

To generate interactive documentation, we use the official Swagger codegen tool with the following command:

`swagger-cli bundle swagger.yaml --dereference --outfile ./gen/api.json`

This generates an api.json file which, when loaded into either the Swagger browser plugin or the official Swagger editor, generates an interactive web page containing both endpoint and model definitions, as shown below:

The Future of API Documentation at Merit

We are experimenting with another tool, Goa, that provides a clean "go DSL" for designing API specs. It is interoperable with Swagger and generates an equivalent Swagger specification (both Swagger v2 and v3). The benefit is the ability to write specifications in "go" directly while the compiler type-checks it, rather than manually writing YAML or JSON.

Pursuing automated testing with tools that generate testing code directly from a Swagger spec, we hope to add another valuable tool that will further shorten the process time and improve clarity and efficiency.

There Are So Many Reasons Merit is a Great Place to Work. Here Are Four More.

Merit transforms large-scale government programs through our technology and expert teams. In practice, we tackle the seemingly impossible, like...

Read More

Free money for back to school? You might qualify for KEEP

TOPEKA, Kan. (WIBW) - You could have free money coming to help with your kids’ back to school expenses.

Read More

6 Ways Technology Helps Meal Management Accountability During Disasters

The Waffle House Index was coined by Craig Fugate, former administrator of FEMA, to unofficially indicate a storm’s impact and the likely scale of...

Read More