Serve API Documentation

An API documentation is a concise reference manual intended for developers.

It contains all the necessary information required to work and integrate with an API and also provides information about the API's lifecycle, such as new versions or retirements.

The OpenAPI Specification defines a standard for describing REST APIs using either the JSON or YAML format, which are easy to learn, and are readable by both humans and machines.

Overview of the OpenAPI document

Just like the Readme file, the OpenAPI file should live in the top-level directory of your project and should be named either openapi.json for JSON format or openapi.yaml for YAML.

This document is usually composed of at least three fields: openapi, info and paths.

Let's create a new file in the root directory of the project named openapi.yaml:

$ touch openapi.yaml

Note: For our purposes, we'll use the YAML format as it offers a more concise syntax.

The OpenAPI version

The openapi string describes the version number of the OpenAPI Specification used in the document, which in turn defines its overall structure.

# File: openapi.yamlopenapi: 3.0.3

The info object