An article discusses how to use Koa2 to integrate Swagger in Node.js projects

In this article, we will explore how to use Koa2 to integrate Swagger in a Node.js project to automatically generate API documentation. We will introduce the basic concepts of Swagger, related NPM packages, and demonstrate the entire process with detailed code examples and explanations.

What is Swagger

Swagger is a document generation tool for RESTful APIs. It can help developers write, maintain and review APIs quickly and accurately. document. Swagger has the following advantages:

• Automatically generate API documents, reducing the workload of manual writing
• Provides visual API interface testing tools to facilitate debugging and verification
• Support Multiple languages ​​and frameworks, with good versatility and scalability

Create Koa2 project

First, we need to create a Node.js project based on Koa2. You can use the following command to create a project: [Recommended related tutorials: nodejs video tutorial, Programming teaching]

mkdir koa2-swagger-demo
cd koa2-swagger-demo
npm init -y

Then, install Koa2 and related dependencies:

npm install koa koa-router --save

Install Swagger-related dependencies

Next, we need to install Swagger-related NPM packages. In this tutorial, we will use koa2-swagger-ui and swagger-jsdoc. Used to display Swagger UI and generate API documentation respectively.

npm install koa2-swagger-ui swagger-jsdoc --save

Configuring Swagger

In the project root directory, create a file named swagger.js for configuring Swagger. The configuration code is as follows:

const swaggerJSDoc = require('swagger-jsdoc');
const options = {
    definition: {
        openapi: '3.0.0',
        info: {
            title: '我是标题',
            version: '1.0.0',
            description: '我是描述',
        },
        //servers的每一项，可以理解为一个服务,实际项目中，可自由修改
        servers: [
            {
                url: '/api',
                description: 'API server',
            },
        ],
    },
    apis: ['./routes/*.js'],
};

const swaggerSpec = swaggerJSDoc(options);

// 如果有Swagger规范文件转TS的需求，可在此处保留Swagger规范文件到本地，方便使用
//fs.writeFileSync('swagger.json', JSON.stringify(swaggerSpec, null, 2));

module.exports = swaggerSpec;

Here, we define an object named options, which contains the basic information of Swagger and the source of the API interface (that is, our routing file). Then, we use swagger-jsdoc to generate the API documentation and export it.

Writing API interface

Now, let’s create a folder named routes, and create a file named users.js in it File used to define user-related API interfaces. In the users.js file, we will write the following code:

const Router = require('koa-router');
const router = new Router();

/**
* @swagger
* tags:
*   name: Users
*   description: User management
*/

/**
* @swagger
* components:
*   schemas:
*     User:
*       type: object
*       properties:
*         id:
*           type: integer
*           description: The user ID.
*         name:
*           type: string
*           description: The user's name.
*         email:
*           type: string
*           description: The user's email.
*       required:
*         - id
*         - name
*         - email
*/

/**
* @swagger
* /users:
*   get:
*     summary: Retrieve a list of users
*     tags: [Users]
*     responses:
*       200:
*         description: A list of users.
*         content:
*           application/json:
*             schema:
*               type: array
*               items:
*                 $ref: '#/components/schemas/User'
*/
router.get('/users', async (ctx) => {
    const users = [
        { id: 1, name: 'John Doe', email: 'john.doe@example.com' },
        { id: 2, name: 'Jane Doe', email: 'jane.doe@example.com' },
    ];
    ctx.body = users;
});

module.exports = router;

Comment brief analysis:

1. tags: This part defines a name The label for "Users". Tags are used to classify and group API interfaces. Here, the label is named "Users" and the description is "Interface under users.js".

   /**
    * @swagger
    * tags:
    *   name: Users
    *   description: users.js下的接口
    */

2. components and schemas: This part defines a data model named "User". The data model describes the data structures used in the API interface. In this example, the "User" model contains three properties: id (integer type, representing user ID), name (string type, representing user name), and email (String type, representing the user's email). At the same time, the id, name, and email attributes are marked as required.

   /**
    * @swagger
    * components:
    *   schemas:
    *     User:
    *       type: object
    *       properties:
    *         id:
    *           type: integer
    *           description: id.
    *         name:
    *           type: string
    *           description: name.
    *         email:
    *           type: string
    *           description: email.
    *       required:
    *         - id
    *         - name
    *         - email
    */

3. /users API interface: This part defines an API interface for obtaining a user list. It describes a GET request with the path /users. This interface uses the "Users" tag defined previously. In addition, it also defines a successful response with a status code of 200, indicating that a user list is returned. The content type of the response is application/json, and its structure is an array containing the "User" model.

   $ref: '#/components/schemas/User' is a reference syntax that refers to the schemas previously defined under components The data model named User.

   /**
   * @swagger
   * /users:
   *   get:
   *     summary: 获取用户列表
   *     tags: [Users]
   *     responses:
   *       200:
   *         description: success.
   *         content:
   *           application/json:
   *             schema:
   *               type: array
   *               items:
   *                 $ref: '#/components/schemas/User'
   */

This code provides the API documentation with details about the user management interface, data model, and response format. Swagger JSDoc parses these annotations and generates corresponding OpenAPI documents.

Generate API documentation

Next, we need to enable Swagger UI in the project. In the project root directory, create a file named app.js and write the following code:

const Koa = require('koa');
const Router = require('koa-router');
const swaggerUI = require('koa2-swagger-ui').koaSwagger;
const swaggerSpec = require('./swagger');
const usersRoutes = require('./routes/users');

const app = new Koa();
const router = new Router();

router.use('/api', usersRoutes.routes(), usersRoutes.allowedMethods());

router.get(
    '/swagger',
    swaggerUI({
        routePrefix: false,
        swaggerOptions: {
            spec: swaggerSpec,
        },
    })
);

app.use(router.routes()).use(router.allowedMethods());

const PORT = process.env.PORT || 3000;
app.listen(PORT, () => {
    console.log(`Server is running at http://localhost:${PORT}`);
});

Here, we imported the API documentation generated by koa2-swagger-ui and swagger-jsdoc. Then, we defined a route named /swagger to display the Swagger UI. Finally, we mount the user-related API interface to the /api path.

Test

node app.js

Open in the browserhttp://localhost:3000/swagger You will see the Swagger UI and automatically generated API documentation.

Summary

In this article, we introduced in detail how to integrate Swagger and automatically generate API documentation in a Node.js project based on Koa2. By using koa2-swagger-ui and swagger-jsdoc, we can easily generate online documentation for API interfaces and utilize Swagger UI for visual testing.

The main steps to integrate Swagger are as follows:

• Install related dependencies: koa2-swagger-ui and swagger-jsdoc
• Configure Swagger: create the swagger.js file, Define the basic information and interface source of the API document
• Write the API interface: Use Swagger annotation syntax to describe the interface information
• Enable Swagger UI: Configure the routing of Swagger UI in app.js and add the API The document is passed to it
• Run the project and access the Swagger UI

Through the above steps, we can realize the automatic generation, update and review of API documentation in the project, thereby improving development efficiency and Collaborative effect. At the same time, using the testing tools provided by Swagger UI, we can also easily verify the correctness and stability of the API interface.

You can use swagger-to-ts to convert Swagger specification files into TypeScript type files.

For more node-related knowledge, please visit: nodejs tutorial!

The above is the detailed content of An article discusses how to use Koa2 to integrate Swagger in Node.js projects. For more information, please follow other related articles on the PHP Chinese website!