Describing an API according to the OpenAPI Specification comes with a wide variety of benefits for maintaining APIs in production, and keeping docs automatically synchronized with your live API.
You don't have to start over designing your API in order to adopt the OpenAPI standard!
If you already have an API designed and in production, you can still document it in an OpenAPI format and open your operation up to all the benefits that come along with using it as a standard.
Open formats like OpenAPI and Swagger mean we save time by not reinventing the wheel with every company creating its own standards. GitHub recently announced they are open sourcing an OpenAPI description of their REST HTTP API.
Let's look at some ways you can generate the descriptions from source code, and from active traffic.
Translate API Definitions to OpenAPI Definitions
If your API is built using a common framework, such as Falcon (Python) or Rails (Ruby), your code already has everything needed to create an OpenAPI description! Look for an existing project that creates an API definition based on an existing API in your framework.
For example, zero-rails_openapi gem is a Rails solution that will translate API descriptions into OpenAPI descriptions, while falcon-apispec does the same for Falcon using Python.
When describing HTTP APIs, you want to keep an overall developer experience in mind. If your documentation is going to be comprehensive, your Swagger or OpenAPI definition must also have full API coverage.
Comment Your Existing Code With OpenAPI
Using the oas module, you can generate an OpenAPI definition from inline YAML. This is a ReadMe open source tool, and we use it internally to document APIs from code! (Don't worry if you don't write Node, the tool works on any language.)
oas allows you to write OpenAPI parameters as inline documentation in the comments as you write the API code. Then oas compiles it all into a single shareable YAML or JSON file that represents the complete OpenAPI description.
There are a lot of ways to create an OAS file, but doing it right in the code is our favorite at ReadMe. This way the spec is always up to date with the code, and makes it easy to integrate with developer tools.
You can also create API descriptions from code comments using a tool like swagger-inline.
Listen to Live API Traffic and Transcribe
Services like Optic listen to live API traffic and note the parameters. After reviewing live requests and responses, Optic can output an OpenAPI or Swagger description file.
Keep in mind that any API description that is created by listening to live traffic will only know about the requests and responses it observes. Therefore, when taking this route, be diligent about checking your generated OpenAPI description and its coverage.
Write OpenAPI Descriptions by Hand
Not satisfied unless you've seen or written every line yourself? Our expansive guide, How to Use OpenAPI and Swagger for Documentation, will get you started with the process. It includes a starter template, and lots of tools you can use to write your own OpenAPI description!
