Your first OpenAPI document (Part I: Introduction)

Document your REST API using OpenAPI standard — Part I: introduction and document outline

One of the most burdensome activity developers constantly face is documenting how their software works. We often try to postpone this annoying task as long as we can, but sooner or later we are gonna spend quite some time on it.

Documenting a REST API has been quite a far west so far: everyone probably did it in an even slightly different way than anyone else. Fortunately time has come for an open standard to describe our API in a machine and human readable format: it’s called OpenAPI and we are going to see how simple and convenient is to use.

Open API Initiative (OAI) — https://www.openapis.org/

OpenAPI strongly encourages you to define all the “building blocks” of your API (security, model, …) and use inheritance and composition to describe API endpoints, making really convenient to start as early as possible even with basic models, since you can refer them from anywhere and keep updating them without changing a single line referring them.

Using OpenAPI, you will soon realize how several common programming language design principles are easily applicable to this context, making documenting your API a much less annoying task.

Introduction

Before start diving into OpenAPI language syntax and nuances, I want to spend a couple of paragraphs discussing the reasons why — in my opinion — we should adopt it right now.

First reason: it’s an open standard. Open means the entire community of stakeholders involved in the so-called API economy can contribute with their own experience, ideas, suggestions and tools. Standard means we all are finally going to have a unique, consistent and well-formed way to describe our API; no one is going to reinvent the wheel again, hopefully.

Second reason: it’s machine readable. If OpenAPI adoption spreads, a new ecosystem of guides, tools, … will grow, speeding up the process of writing documentation, testing our API and even automatically generating code for client/server applications in our preferred programming language or framework.

The Swagger team, who came up with an attempt of standardizing API documentation which gave birth to OpenAPI, already made available several open-source tools to achieve these goals:

• Swagger Editor: write and test documentation from your browser
• Swagger UI: publish your documentation online
• Swagger Codegen: generate client/server code skeletons

These tools are a striking example of what we can achieve using an open standard no matter when we start documenting our REST API:

• if we start late (e.g. after development) and we already have a running instance of our application, we can test all endpoints straight from Swagger Editor, ensuring they behave exactly like our documentation specifies;
• if we start early (e.g. at design), we can use Swagger Codegen to generate a skeleton for the client and/or server component of our application, such relieving ourselves from the boring part of the development process.

So, if you are still with me and I convinced you OpenAPI is worth a try, let’s recap with a definition from OpenAPI Initiative website:

The OpenAPI Specification (OAS) defines a standard, programming language-agnostic interface description for REST APIs , which allows both humans and computers to discover and understand the capabilities of a service without requiring access to source code, additional documentation, or inspection of network traffic.

OpenAPI language

OpenAPI it’s a data serialization language (JSON is another quite famous example of such a language) based on YAML, much like HTML is a markup language based on XML. YAML defines the basic syntax, conveying the human (and machine) readability of the document, while OpenAPI defines the grammar you can use, i.e the detailed specification of the document structure.

For those of you which are not familiar with YAML (or one of its many “children”), these are its main features:

• use indentation whitespaces to define structure (informations are organized hierarchically)
• list elements are denoted by a leading hyphen (one per line) or enclosed in square brackets and separated by comma
• associative arrays /object fields are written as key: value (one per line)
• strings are generally unquoted, but may be enclosed in double or single quotes

For a detailed syntax description, take a look at YAML Wikipedia page and official website. Now let’s look at an example of a YAML document:

As you can probably see, reading and understanding a YAML file is quite trivial, you do not need to know (almost) anything about its syntax. At the same time a machine can easily parse it too. Really nice, don’t you think?

Document outline

So, let’s imagine we need to write a basic CRUD REST API for our book catalog. In our OpenAPI practical tour, which will span several articles, we are going to expand from the example shown just before, starting with a basic document which could look like this:

In the following sections (and articles) I’m going to follow some formatting conventions when referring OpenAPI language elements:

• optional property: italic
• required property: bold*
• property type: type

Schema

Every OpenAPI document begins with a line containing the schema information, i.e. the version of OpenAPI specification the document conforms to. We use the latest available (3.0 as time of writing) and whenever a new version comes out, even if it’s not backward compatible with the version of our choice, our document will (hopefully) still be parsed and interpreted correctly.

Basic information

The info section contains essential API project information:

• title* string
• version* string : semantic versioning should be used
• description string
• terms of service string : must be an URL
• license object : only name field is required
• contact

Servers

This is probably the most important basic section from a testing perspective. If you recall, I mentioned we could not only write our documentation but also test our endpoints straight from the browser.

In this section we indicate the base URL of any application instance we want to be able to test our API against, so we should carefully choose which applications to include, e.g.:

• your local/development instance (yes, but be sure all developers of your team have the same setup — e.g. using Docker — if you are going to put this lines under version control)
• testing instance (for sure)
• production (definitely not)

Each server must have an url* string and can have a description string. In addition, you can use placeholders (read variables) within the server name (like port number) but it’s a quite advanced use case; if you are interested, take a look at OpenAPI specifications.

Tags

A tag has one primary purpose: make it easier to classify API methods and display them grouped; in our example, we are probably going to have API endpoints to perform basic CRUD operations on books and authors, so we add these two tags.

Each tag must have a unique name* string and can have a description string.

Paths

All API endpoints (paths in OpenAPI vocabulary) are documented under the the paths section along with:

• supported HTTP methods (operations in OpenAPI vocabulary)
• request parameters (query string, headers, …) and body
• response

Models

All models informations are located under components/schemas section.

In the next article of this series I will show you how easily we can document our data model.