API Documentation with OpenAPI

Last Update: 21.11.2017. By Jens in APIs | API Business

This is the fourth part of the API documentation series. In the last part we explored RAML as a solution, and in this article, we are covering OpenAPI.

OpenAPI

OpenAPI is another specification for describing APIs, with a focus on REST APIs. The idea is that you have precisely one documentation which suits humans and machines alike. The API is documented in a JSON format either as plain JSON directly or with YAML following the JSON structure. The format is very technical by nature, and even the editor tools like Swagger Editor are targetted at tech folks.

I’d classify it more as a type 2 - docs close to the source code. You could write the documentation separately, and there are even visual tools. But by its nature, it tends more towards devs and documenting close to the source code.

As with our other candidates, it has a healthy ecosystem and tools for various tasks, ranging from visual editors to code generators.

Our previous example would look as YAML like:

swagger: "2.0"

info:
  version: 1.0.0
  title: Book API
  description: Book metadata API description

schemes:
  - https
host: books.example.com
basePath: /v1

paths:
  /books:
    get:
      summary: Get metadata of our books
      description: Returns a list containing all books
      responses:
        200:
          description: A list of books
          schema:
            type: array
            items:
              required:
                - isbn
              properties:
                title:
                  type: string
                isbn:
                  type: string

Using the Swagger Editor, the documentation will look like:

Details of an endpoint will show after a click on it, and it even provides a way to directly try out the API requests inside of the documentation.

Advantages

It is open source as the others specs/languages and is based on standard formats and technologies.

It defines a rigorous structure to document your API. This is necessary when making it also readable for machines. This has the advantage that you can develop universal tools, like for example tools for querying the API, It also has the benefit that one can just point his OpenAPI compatible tool against your API and can operate on it.

This is the most significant advantage OpenAPI has over the other solutions.

Disadvantages

All of the solutions share the same common disadvantage that they are build for REST-like web APIs and everything beyond that is not supported.

However, the most significant disadvantage is that it is primarily made for developers. When used in the code base, it is solely the job of your devs to take care of the documentation. And thus you are bound to the release cycles of your applications.

When used as a separate documentation, a non-dev could write the documentation. But as with RAML, it needs to be someone with technical skills and a high comfort level. Even when using a visual editor, knowledge of the terms is necessary.

Conclusion

It is a mature spec and has been now as Swagger for quite some time. It is definitely built for devs who want to document their API along the code. However, if it fits your organization, it still is a good choice.

In the next and last article of the series, we will take a look at a platform-specific solution, Spring REST docs.