Let's start getting our most important dependency, Swagger. Remember that we will use NPM to download Swagger, because we will use it on a ExpressJS API. Swagger has its own implementation depending on the platform you need to document.

There are two very famous swagger implementations to integrate with an ExpressJS application:

• swagger-node-express
• swagger-ui-express

The swagger-node-express is the official Swagger module for Node. Some of the most interesting (and not so) characteristics of this library are as follows:

• Official distribution of the Swagger API. We are fully supported by an organization working actively on the development of the product.
• It is open source.
• Comes with Swagger Editor and Swagger Codegen.
• Swagger UI needs to be inserted inside the code where we are adding documentation.
• Since documentation is quite poor, you need to read the source code of some different libraries to learn and understand each argument used to configure Swagger.

The swagger-ui-express is supported by the community, another great open source option. How does it work? This library adds a middleware to your Express.js application that serves the Swagger UI bound to your Swagger document. It's really easy to configure; the only thing you will need to perform is add one route to host Swagger UI, without need to copy anything manually. Documentation is really good, and we think everything you need should be there.

Given the functionality and simplicity of this tool, we've decided to use this library instead of any other option to achieve our main goal of documenting our application.

To get started, we need to add the library to our current project:

npm install -save swagger-ui-express

Once the library is added to our project, we need to configure a route to host Swagger UI. Also, we need to load the Swagger API definition of our application. In our application, the Swagger API definition is a single file containing information about our application represented in a JSON object.

To create the Swagger API definition, we have used Swagger Editor. Remember that you are free to use JSON or YAML notation. Let's look at an example of the same definition in different formats:

In JSON it is done as follows:

{
    "swagger": "2.0",
    "info": {
        "version": "1.0.0",
        "title": "WorldCup API",
        "description": "A simple API to learn how to write FIFAWC Specification"
    },
    "schemes": [
        "http"
    ],
    "host": "localhost:3000",
    "basePath": "/",
    "paths": {
        "/teams": {
            "get": {
                "summary": "Gets team list",
                "description": "Returns a list containing all teams of the WorldCup.",
                "responses": {
                    "200": {
                        "description": "A list of Teams",
                        "schema": {
                            "type": "array",
                            "items": {
                                "teams": {
                                    "country": {
                                        "type": "string"
                                    },
                                    "trainer": {
                                        "type": "string"
                                    }
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}

In YAML:

swagger: "2.0"

info:
  version: 1.0.0
  title: WorldCup API
  description: A simple API to learn how to write FIFAWC Specification

schemes:
  - https
host: simple.api
basePath: /doc

paths:
  /teams:
    get:
      summary: Gets teams list
      description: Returns a list containing all Teams of the WorldCup.
      responses:
        200:
          description: A list of Teams
          schema:
            type: array
            items:
              properties:
                country:
                  type: string
                trainer:
                  type: string
                

Both are very human readable.

Even if our specification file is a text that can be edited with any text editor, nowadays we have many specialized tools to achieve this, giving us some useful features such as syntax validation, format, autocomplete parameters, and more. The best option to write specification file is Swagger Editor (yes, its own tool), a powerful set of static files that allows you to write and validate Swagger specification in YAML syntax and see how your file will look rendered.

The created Swagger API definition will be stored in our application as a JSON object inside the swagger.json file. At this moment, our setup script should look like this:

const swaggerUi = require('swagger-ui-express')
const swaggerDocument = require('./swagger.json'); //Our specification file

app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument));

As you can see, first middleware is setting up our Swagger server. This middleware will return static files that are needed for hosting Swagger UI. Second middleware is our setup function that will set up Swagger UI to use our predefined users parameters in the json/yml file.

Also, of course, our documentation URL is http://localhost:3000/api-docs.