The accompanying diagram is intended to help you quickly decide how to document an API, but particularly a REST API. The first split is just to make sure you are looking for the right kind of API.
Here is some more context to help you decide on an approach and get started.
- native API
-
A platform for exploiting or extending an application in its original (or ported) source language. Entails programming in the source language. Most languages have one or more syntaxes/utilities for translating API source code into reference documentation.
- REST/RESTful API
-
A server-side interface specially structured to accept requests from client apps and services using standard HTTPS protocol and methods (
GET,POST, etc). The dominant standard for remote APIs, and presently the most common intended meaning of the term “API” in general. - GraphQL API
-
A remote, HTTP interface that uses sophisticated queries (QL for query language) instead of hyper-specific endpoints like REST. See this Hackernoon article for advice on documenting GraphQL APIs.
- design-first API development
-
All changes to the API are first made to a definition document that becomes a contract for developers, quality assurance, and so forth. See Design-first Resources below.
- code-first API development
-
Docs are generated from or otherwise based on the API code, which is developed/committed first. Generate an OpenAPI description document from source code, then generate HTML documentation from that. See Code-first Resources below.
- OpenAPI
-
Formerly Swagger, te OpenAPI standard is open sourced and directed by the OpenAPI Initiative. Widely adopted and supported across the industry, OpenAPI documents (OAD) can be formatted as JSON or YAML.
- RAML
-
Stands for RESTful API Modeling Language, a YAML-formatted standard for defining and documenting HTTP APIs. The main alternative to OpenAPI, but the project is dormant, as well as being weakly supported by third-party tooling. See the raml.org site.
- docstrings
-
Markup embedded in commented-out lines in the API source files. Used by an OpenAPI description generator to convey certain metadata to the OAD file in a code-first process.
- OpenAPI Overlays
-
An official extension of OpenAPI that enables gracefully modifying OpenAPI description/definition documents. See OpenAPI Overlays for information on using Overlays to augment code-first strategy.
TipOverlays are strongly advised for enriching documentation for a code-first approach, but they can also be used with design-first, especially for such modifications as internationalization or releasing multiple editions of a core API. - CI/CD
-
Continuous integration and deployment. More broadly, whatever automation tooling your organization uses to build, test, and deliver software and documentation.
- single source of truth (SSoT)
-
A principle of technical documentation and quality assurance practice that encourages maintaining reusable, modularized, machine-readable designations of key product details. The single source need not be centralized, but the implementation and documentation and testing of each product attribute or function must derive from one canonical source.
This key document is either manually authored (“design-first”) or auto-generated (“code-first”). In the former case, we tend to call it a definition. We refer to an auto-generated file as a description.
OpenAPI description and definition files are also referred to as “documents” (OAD, for short), not to be confused with the documentation that can be generated from them. RAML is a design-first format, so these documents are called “API definitions”.
Both OpenAPI and RAML depend on official specifications. The OpenAPI Specification (OAS) is the standard that your OAD files must adhere to and related tooling must support. Likewise, the RAML Specification designates RAML syntax and tooling requirements.
These description/definition documents are often mistakenly called “specifications”, including in resources linked here. However, to avoid confusion, it is best to refer to the actual OpenAPI and RAML standards as “specifications”.
For OpenAPI, this highlights the important distinction between OAS and OAD. The first is the standard/specification, the second is your design/definition document.
If you are able to work with a design-first approach, your needs are going to be mainly philosophical, at first. The whole team has to get on board with the approach, which will take some coordination.
|
Note
|
The “design-first” strategy is not to be mistaken for the “API-first” approach. The latter is a broader recommendation for holistic application development, focusing on modeling/building the REST interface ahead of backend infrastructure or frontend/client interfaces. It is possible (even common) to use an API-first and code-first technique. |
Here are some articles on API design-first strategy:
If you’re going with code-first, your OpenAPI description will need to be generated and finessed.
|
Note
|
The OAD file generated from a code-first approach is the opposite of a specification — it is at best a 1:1 report. |
|
Note
|
Code-first strategy can provide a single source of truth (SSoT). Even when augmented by additional sources, SSoT is maintained so long as each attribute of the product is backed by a particular datum, which is also drawn on for docs and tests. |
These sections cover topics related to making code-first strategy work.
The code-first approach, as well as the docs-last strategy, depend on auto-generating a “draft” of the OpenAPI description file. This means translating so-called “native” code to OpenAPI, usually outputting a single JSON file.
A great list is maintained at OpenAPI.Tools.
Rarely will an auto-generated OAD take full advantage of OAS 3.x features, so teams need a plan for maintaining augmented description documents without constantly overwriting changes when a new OAD is generated. This is where OpenAPI Overlays can come in handy.
The alternative is an ad-hoc solution that usually involves Git and a script that will hopefully merge edits on the previous version onto the new version. If you know Git, you already see the challenge.
OpenAPI Overlays promise to meet this challenge, letting you map properties onto existing nodes. You can modify description fields, add examples or schemas to various operations, and so forth.
This is not intended to be an exhaustive reference to 3rd-party tools and articles on OpenAPI. Just to maybe get you grounded.
This section will be maintained over time, so suggestions are welcome, and any such comments will help regardless.
To this day the definitive resource on REST API documentation has to be Tom Johnson’s free course: “Documenting APIs: A guide for technical writers and engineers”.
The aforementioned OpenAPI.Tools site is a great resource for lots more than just auto-generators.
The official OpenAPI Tooling database seems to be a mirror or superset of the content at OpenAPI.Tools.
The redocly-cli utility is a widespread favorite, owing to its conversion power when it comes to converting OpenAPI documents.
Mainly for code-first, but also maybe for design-first projects, the openapi-format commandline utility is your friend. It is especially advantageous for restructuring OpenAPI documents and applying OpenAPI Overlays.
|
Note
|
Redocly has its own alternative to overlays, at least for replacing the code-first augmentation proposed here. This “decorators” solution works with their CLI tool as well as their cloud platform. |
Some people swear by the manual effort of meticulously reporting every new change from the API source to the OpenAPI description document. They do not depend on or mess with the automation overhead required to maintain auto-generated code using this or that “hack”.
This is fair enough. If you and your team work better with this documentation approach, by all means use it.
However, as general advice, I think it is important to:
-
highlight just what can be automated in an OpenAPI toolchain
-
promote single-sourcing as a first principle of technical documentation practice
It also generally makes sense for someone in the role of product manager or product owner to designate the way an application should work, or at least approve relatively code-free proposals or specification/requirement docs. OpenAPI definition documents fulfill this in a way non-programmers can read and write.
This guide does not cover advanced topics with regard to implementation of an API/docs platform. Readers just getting into API documentation will want to explore at least the following topics:
- Non-reference documentation
-
Everything above is about automating and canon-securing your API reference documentation. But reference docs always need to be augmented and supplemented with explainers and tutorials.
These contextual docs should cover topics like authentication, security, and policies particular to your API.
- Versioning and lifecycle management
-
API docs should correlate to product releases, but a plan for this needs to be done up front, especially for code-first systems.
- API governance and style guides
-
Use linters to evaluate all aspects of the API, including the content of the description fields as well as the validity and consistency of all OpenAPI document properties.
To be honest, I have not even gathered resources on these matters, and I have no expertise on them, but they are serious considerations nonetheless.
Please do not spam the comments with suggestions of your own commercial solutions. If you work for a project or have any conflict of interest, please do not post unless to reply to a comment about your product.
If you are a satisfied or disappointed user of a given product or method, feel free to say so.
If your feedback does not get reflected in later revisions of this document or the flowchart, keep in mind that brevity is a key consideration for both. This is NOT intended to be an exhaustive resource.