Previous posts showed how to write a highly accurate description of an API interface contract with the OpenAPI specification. But an interface contract, no matter how brilliant, is nothing without some explainations. A fully documented OpenAPI specification file can provide some useful information and be used as a part of an API’s documentation.

Writing OpenAPI (fka Swagger) Specification tutorial

This tutorial is composed of several posts:

In previous parts we’ve learned to create highly accurate API description, in this seventh part we’ll learn how to use the OpenAPI specification to make it a valuable part of an API documentation.

All tutorial’s files are available on GIST.

If you’re a bit lost in the specification, take a look at my [visual documentation:

API’s general informations

First things first. When using an API, API consumers want to have some general informations about it like its version, its name, some description, term of service, how to contact the API provider, what kind of licencing it uses. The info object placed on root level can be used to provide such information:

Categorizing operations with Tags

By using tags on operation level, we can categorize operations. tags is a simple list of names.

Single tag

This operation belongs to the Person category:

Multiple tags

An operation can belong to different categories:

Descriptions everywhere

We can add some descriptions at almost every level of the OpenAPI specification.

Security definitions

A description can be added to security definitions:

Schema title and description

Each schema (used in a definition, a parameter or a response) can have a title and a description:

Property description

Properties can be described with description:

Parameter’s description

Whether defined inline or in parameters section, a parameter can have a description.

Inline parameter’s description

Reusable parameter’s description

Operation’s summary, description and operationId:

An operation can be described with a summary and a longer description. An operationId can be added. It can be used as a link to the implementation running behind the API for example.

Response’s description

Whether inline or defined in responses, a response can have a description.

Inline response’s description

Reusable response’s description

Reponse’s header’s description

Headers returned with a response can have a description:

Tags descriptions

Tags can have descriptions. We need to add a tags section on specification file root level, on each item in this list we set a name (corresponding to the name used in tags list on operation level) and a description:

Using GFM in descriptions

In almost all description, we can use GFM (Github Flavored Markdown). To check if an object description support GFM, take a look at my visual documentation or the original specification. Note that GFM support can vary depending the tool processing the OpenAPI specification file.

Simple multiline description

By adding a | and a new line with a new tab, we can write multiline descriptions:

Simple GFM description

Description with array

Description with code


Examples can be provided for atomic or object properties, definitions, and responses.

Atomic property example

Atomic properties can be illustrated with an example:

Object property example

Object properties, can also be illustrated with a complex example complying to the underlying JSON Schema:

Definition Example

An example can be defined for the entire definition just like for an object property (it must conforms to its underlying JSON schema):

Response’s Example

On response level, we can provide example, each one corresponding to a media type returned by the operation. Here’s an example for an application/json media type:

Examples precedence

If we defined examples on multiple levels (property, object, definition, response), it’s always the higher level which is taken into account by tools processing OpenAPI specification file.

Operation’s deprecation

An operation can be deprecated by setting deprecated to true:

Links to external API documentation

In most case, the OpenAPI specification file MUST NOT be the only API’s documentation. How to create an application key, use cases, operation chaining and many other things need to be documented. All these other documentations can be separated from the specification file. However, the OpenAPI specification allow to provide links to these other documentations when needed.

We can add an externalDoc object on root level with a link to the API documentation.

Each operation can have its own link to an external documentation using the same externalDoc object:

A tag’s description can also provide an external link:


Even if an OpenAPI specification MUST NOT be the only documentation for an API, it can be a good part of it, and you now have mastered this aspect of the specification. In next post we’ll see how we can split a OpenAPI specification file in different files.