Document APIs with Swagger (3/4) — Setting up the set

In this series of articles, I will introduce the different Swagger tools. Swagger is a very handy tool for API documentation. It allows you to generate “living” documentation, so that the documentation is always up to date, which is very difficult to do without this kind of tool. It also allows to generate code automatically, allowing the developer to focus on his core business. Finally, it is based on an open source specification format.

These articles focus on Swagger 2.0, while the 3.0 version (“OpenAPI 3.0.0”) is available.

This article is thus broken down into four parts :

There are two ways to use the documentation:

  • by Swagger UI embedded in the server,
  • or by Swagger UI running autonomously.

Use of Swagger UI embedded in the server

Setting up the environment

The result of the command is:

Install the dependencies:

The output of the command is:

Launch the server:

NodeJS indicates that the server is running by specifying the listening port:

Checking that the server is properly installed

Check that the server responds correctly:

  • Go to the documentation at http://0.0.0.0:8080/docs.
  • Click Contact.
  • Click on the GET /contact route.
  • Click on Try it out!
  • The Response Body frame displays no content: the result is empty.

This is normal. We will modify the server source code to return data.

Modification of the server to return data

Stop the NodeJS server.

Edit the file ./out/service/ContactService.js and replace the :

by:

Restart NoteJS :

NodeJS confirms that the server is restarted:

Verify that the server is returning data as expected

Verify that the server is returning data:

  • Return to http://0.0.0.0:8080/docs.
  • Refresh the page.
  • Click on Contact.
  • Click on the GET /contact route.
  • Click on Try it out!
  • The Response Body frame displays :

So Swagger displays well the data we have added in the API.

Using Swagger UI running autonomously

This scenario corresponds to the case where the server source code was not generated by Swagger Codegen CLI.

We have already created the specifications. You must have specified the host with its port and the scheme (HTTP or HTTPS) in the specifications.

Launch the REST API server:

The result of the command is:

Start the Swagger UI server:

The result of the command is:

Verify that the API call to display the contact list fails

  • Go to the documentation at http://0.0.0.0:83.
  • Click on the Get the list of contacts line.
  • Click Try it out.
  • Click Execute.

An error message is displayed in the Chrome browser console: blocked by CORS policy.

You must enable CORS in the NodeJS server.

Activation of CORS in the NodeJS server

Edit the index.js file and add the following code before the line // Initialize the Swagger middleware:

Run the request again in Swagger: the error message in the web browser disappears.

The Response Body frame then displays:

The Swagger framework is based on OpenAPI Specification.

The specifications are written in YAML or JSON.

Swagger includes several sub-projects responding to a specific objective:

  • Swagger Editor: to edit specification files in YAML format;
  • Swagger UI: to display and run Swagger specification files interactively;
  • Swagger CodeGen: to read specification files and generate client and server skeleton code.

More articles on my blog http://www.DevOpsTestLab.com.

My DevOpsTestLab Youtube channel.

My LinkedIn profile: https://fr.linkedin.com/in/brunodelb

Interests in the full lifecycle: design, Agile Coaching, development, testing, DevOps, Cloud, Management 3.0, ITIL. It defines me.

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store