35. Documenting NodeJS API's with Swagger

One of the most important parts of API development is the documentation. Documentation is essential so that other developers can understand how to use the API, what features are available, what are the input parameters and expected response formats. In the NodeJS universe, one of the most popular tools for API documentation is Swagger. In this chapter of our e-book, we'll dive into the documentation of NodeJS APIs with Swagger, from basics to advanced.

What is Swagger?

Swagger is an open source software framework, sponsored by SmartBear Software, that helps developers design, build, document, and consume RESTful APIs. Swagger is made up of a large ecosystem of tools that includes both open source software and commercial tools. Some of the most notable tools include Swagger UI, Swagger Editor and Swagger Codegen.

Why use Swagger?

Swagger is widely adopted and has an active developer community. It provides an easy way to document RESTful APIs and also makes it easy to generate client code in multiple languages. Furthermore, Swagger UI provides a nice graphical interface for interacting with the API, which can be very useful for testing and demos.

Introduction to Swagger in NodeJS

To start using Swagger in a NodeJS project, you will need to install the npm package 'swagger-ui-express' and 'swagger-jsdoc'. 'swagger-ui-express' is used to host API documentation while 'swagger-jsdoc' is used to generate API documentation based on JSDoc comments in code.

After installing the packages, you can configure Swagger in your express application. First, you need to create a swaggerDefinition configuration option that specifies basic information about the API, such as title, version, and description. Next, you need to specify the paths to the files that contain the API documentation in JSDoc format. Finally, you can use 'swaggerUi.serve' and 'swaggerUi.setup' to add routes to your application that will serve the API documentation.

Documenting routes with Swagger

To document a route with Swagger, you need to add a JSDoc comment above the route definition. This comment should include a description of the route, the expected input parameters, and the expected response format. Swagger uses this information to generate API documentation.

For example, to document a GET route that returns a list of users, you could use the following JSDoc comment:

/**
 * @swagger
 * /users:
 * get:
 * description: Returns a list of users
 * responses:
 * 200:
 * description: A list of users
 * schema:
 * type: array
 * items:
 * $ref: '#/definitions/User'
 */

This documentation indicates that the '/users' route accepts a GET request and returns a 200 response with a list of users. The 'User' definition is referenced here, which should be defined elsewhere in the documentation.

Documenting Models with Swagger

Models in Swagger are used to define the structure of objects that are sent or received by the API. For example, in the previous example, we referenced a 'User' definition. Here is how you can define this template:

/**
 * @swagger
 * definitions:
 *User:
 * properties:
 * name:
 * type: string
 *       email:
 * type: string
 */

This documentation defines a 'User' model with two properties, 'name' and 'email', both of type string.

Conclusion

Documenting your APIs is an important practice that makes life easier for developers using your API. Swagger is a powerful tool that makes documenting RESTful APIs in NodeJS an easy and enjoyable task. We hope this chapter has provided a good introduction to using Swagger to document NodeJS APIs.