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.yaml

openapi: 3.0.3

The info object

The info object provides metadata about the API itself.

# File: openapi.yaml
# ...

info:
  title: Node.js App
  summary: A Node.js authentication service powered by Express.js
  contact:
    name: Razvan Ludosanu
    url: https://learnbackend.dev
    email: razvan@learnbackend.dev
  license:
    name: MIT
  version: 1.0.0

The only two mandatory fields are:

• The version which is an arbitrary string specifying the version of the API (e.g. 1.0, and so on) that shouldn't be mistaken with the OpenAPI version.

• The title which is a string representing the name of the API.

The paths object

The paths object holds the relative paths of the API endpoints and their HTTP methods, also called operations.

# File: openapi.yaml
# ...

paths:
  /health:
    get:
      # ...
  /auth/login:
    post:
      # ...

The operation object

An operation object is usually composed of:

• A mandatory responses object that describes the HTTP responses returned by this route.
• An optional description string that describes the route itself.
• An optional requestBody object that specifies the parameters contained within the payload.

# File: openapi.yaml
# ...

paths:
  /health:
    get:
      description: A health check route for external monitoring
      responses:
        # ...
  /auth/login:
    post:
      description: A route for authentication
      requestBody:
        # ...
      responses:
        # ...

The requestBody object

A requestBody object is similar to a response object and is composed of a MIME type and a request schema, which can be completed with the required field that indicates which of the body properties must be included in the payload.

# File: openapi.yaml
# ...

paths:
  /health:
    get:
      description: A health check route for external monitoring
      responses:
        # ...
  /auth/login:
    post:
      description: A route for authentication
      requestBody:
        content:
          'application/x-www-form-urlencoded':
            schema:
              type: object
              properties:
                email:
                  description: A valid email address
                  type: string
                password:
                  description: A password
                  type: string
              required:
                - email
                - password
      responses:
        # ...

The response object

A response object is composed of an HTTP status code, an optional description, a MIME type and a response schema.

# File: openapi.yaml
# ...

paths:
  /health:
    get:
      description: A health check route for external monitoring
      responses:
        '200':
          description: Responds with information about the process
          content:
            'application/json':
              schema:
                type: object
                properties:
                  uptime:
                    description: The number of seconds elapsed since the process started
                    type: number
                  timestamp:
                    description: The number of milliseconds elapsed since Epoch
                    type: number
  /auth/login:
    post:
      description: A route for authentication
      requestBody:
        content:
          'application/x-www-form-urlencoded':
            schema:
              type: object
              properties:
                email:
                  description: A valid email address
                  type: string
                password:
                  description: A password
                  type: string
              required:
                - email
                - password
      responses:
        '200':
          description: User successfully logged in
          content:
            'application/json':
              schema:
                type: object
                properties:
                  token:
                    description: A JSON web token containing the user's ID
                    type: string
        '400':
          description: Bad Request
          content:
            'application/json':
              schema:
                type: object
                properties:
                  message:
                    description: Invalid email address or password format
                    type: string
        '401':
          description: Unauthorized
          content:
            'application/json':
              schema:
                type: object
                properties:
                  message:
                    description: Password doesn't match hash
                    type: string
        '404':
          description: Not Found
          content:
            'application/json':
              schema:
                type: object
                properties:
                  message:
                    description: Email address not found
                    type: string

Serve a JSON API document as HTML

When developing a public API with the Express framework, the easiest way to make its API documentation available to other developers is to use the swagger-ui-express module that allows us to serve OpenAPI documents written in JSON as HTML pages via a dedicated route.

$ npm install --save swagger-ui-express

To load and serve the OpenAPI document through the method of the application on the GET /docs path using the serve() middleware and the method as follows:

const express = require('express');
const swaggerUi = require('swagger-ui-express');
const document = require('../openapi.json');

const app = express();

app.use('/docs', swaggerUi.serve, swaggerUi.setup(document));

app.listen(3000);

We can now open a new tab in our browser at the following address http://127.0.0.1:3000/docs to access the OpenAPI HTML page.

Serve a YAML API document as HTML

To serve an OpenAPI document written in YAML, you'll also need to install a module that converts YAML to JSON.

$ npm install --save yamljs

And load the document using the YAML.load() function instead of the global require() function.

const express = require('express');
const swaggerUi = require('swagger-ui-express');
const YAML = require('yamljs');

const document = YAML.load('./openapi.yaml');

const app = express();

app.use('/docs', swaggerUi.serve, swaggerUi.setup(document));

app.listen(3000);

We can now open a new tab in our browser at the following address http://127.0.0.1:3000/docs to access the OpenAPI HTML page.

Summary

Here's a summary of what you've learned in this lesson:

• Software documentation is a written piece of text or illustrations that come with computer software whose primary goal is to explain how it works and how to use it.
• A Readme file is a plain text file that contains configuration, installation and operating instructions, as well as features, known bugs, licensing and contact information.
• An API documentation is a reference manual that contains all the information required to work and integrate with an API and also provides information about the API's lifecycle.