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:
- Part 1: Introduction
- Part 2: The basics
- Part 3: Simplifying specification file
- Part 4: Advanced data modeling
- Part 5: Advanced input and output modeling
- Part 6: Defining security
- Part 7: Documentation
- Part 8: Splitting specification file
- Part 9: Extending the OpenAPI specification (coming soon)
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
tags on operation level, we can categorize operations.
tags is a simple list of names.
This operation belongs to the
An operation can belong to different categories:
We can add some descriptions at almost every level of the OpenAPI specification.
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
Properties can be described with
Whether defined inline or in
parameters section, a parameter can have a
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
operationId can be added. It can be used as a link to the implementation running behind the API for example.
Whether inline or defined in
responses, a response can have a
Inline response’s description
Reusable response’s description
Reponse’s header’s description
Headers returned with a response can have a
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
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
Object property example
Object properties, can also be illustrated with a complex
example complying to the underlying JSON Schema:
An example can be defined for the entire definition just like for an object property (it must conforms to its underlying JSON schema):
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:
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.
An operation can be deprecated by setting
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.
Link to general API documentation
We can add an
externalDoc object on root level with a link to the API documentation.
Link to specific operation documentation
Each operation can have its own link to an external documentation using the same
Link to tag documentation
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.