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
info:
title: API example
description: A multiline description that accepts ** CommonMark **!
version: 0.1.1
servers:
- url: https://api.grafikart.fr/v1
description: A description of the server (optional)
paths:
/ Users:
get:
summary: Returns the list of users.
description: A longer description explaining the principle
responses:
'200':
description: A table containing the list of users
happy:
application / json:
diagram:
type: array
items:
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).
