Video Tutorial Documenting its API with OpenAPI (Swagger)

In this tutorial I propose to discover how to properly document your APIs with OpenAPI and Swagger tools.

Swagger! = OpenAPI

Before you talk about the tool it's important to clarify the difference between Swagger and OpenAPI. But to summarize:

  • OpenAPI, refers to the specification.
  • Swagger, is the set of tools to work with the specification.

At first the specification was called Swagger but when SmartBear acquired the specification was given to the OpenAPI initiative and renamed OpenAPI. The Swagger brand has been retained for commercial / open source products that work with the specification.

Basic principles

OpenAPI allows to detail the operation of an API through a file in the format yaml or json.

openapi: 3.0.0
  title: API example
  description: A multiline description that accepts ** CommonMark **!
  version: 0.1.1
  - url:
    description: A description of the server (optional)
  / Users:
      summary: Returns the list of users.
      description: A longer description explaining the principle
          description: A table containing the list of users
            application / json:
                type: array
                  type: string

The set of possible options are detailed in the documentation.

It is possible to work on your specification with different tools offered by Swagger but you can also generate your specifications thanks to tools specific to your language (for example you can use PHP annotations).