Dollars in Our Pockets: The Evolution of Direct-to-Beneficiary Programs in America
The United States has a long history of using direct-to-beneficiary (D2B) programs to support those in need, from food assistance to educational...
2 min read
Erik Haliewicz Dec 15, 2022 12:35:12 PM
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.
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:
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:
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:
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.
The United States has a long history of using direct-to-beneficiary (D2B) programs to support those in need, from food assistance to educational...
The workforce is increasingly shifting toward a technology-driven landscape to meet the needs of a skills-based economy. As the National Skills...