在nodejs中使用swagger方式

在Node.js中使用Swagger，可以方便地管理API文档和服务器端点。下面是在Node.js中使用Swagger的完整攻略：

1. 安装swagger-ui-express和swagger-jsdoc依赖：

使用npm安装依赖：

npm install swagger-ui-express swagger-jsdoc

1. 在需要使用Swagger的Node.js文件中导入Swagger：

const swaggerUi = require('swagger-ui-express');
const swaggerJSDoc = require('swagger-jsdoc');
const express = require('express');
const app = express();

1. 配置Swagger：

const swaggerOptions = {
    swaggerDefinition: {
        info: {
            title: 'My API',
            description: 'My API description',
            contact: {
                name: 'My API team'
            },
            servers: ['http://localhost:3000']
        }
    },
    apis: ['./routes/*.js'] //定义API源文件位置
};

const swaggerDocs = swaggerJSDoc(swaggerOptions);
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocs)); //定义Swagger UI路由

1. 编写API文档注释：

/**
 * @swagger
 * /example:
 *   get:
 *     description: Get example data
 *     responses:
 *       200:
 *         description: Success
 *       404:
 *         description: Not found
 */

1. 启动服务器，访问Swagger UI：

app.listen(3000, () =>
  console.log('Swagger is running on http://localhost:3000/api-docs')
);

接下来，我们将通过两个示例来进一步学习Swagger的使用。

示例1：创建一个简单的API并使用Swagger显示文档

1. 创建一个新的Node.js文件，将其命名为app.js，并编写如下代码：

const swaggerUi = require('swagger-ui-express');
const swaggerJSDoc = require('swagger-jsdoc');
const express = require('express');
const app = express();

const swaggerOptions = {
    swaggerDefinition: {
        info: {
            title: 'My API',
            description: 'My API description',
            contact: {
                name: 'My API team'
            },
            servers: ['http://localhost:3000']
        }
    },
    apis: ['./routes/*.js']
};

const swaggerDocs = swaggerJSDoc(swaggerOptions);
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocs));

/**
 * @swagger
 * /example:
 *   get:
 *     description: Get example data
 *     responses:
 *       200:
 *         description: Success
 *       404:
 *         description: Not found
 */
app.get('/example', (req, res) => {
  res.send('Example data');
});

app.listen(3000, () =>
  console.log('Swagger is running on http://localhost:3000/api-docs')
);

1. 在命令行中运行以下命令，启动服务器：

node app.js

1. 访问以下网址，以查看Swagger UI文档：

http://localhost:3000/api-docs/

示例2：使用Swagger编写一个包含Query字符串的复杂API

1. 创建一个新的Node.js文件，将其命名为app.js，并编写如下代码：

const swaggerUi = require('swagger-ui-express');
const swaggerJSDoc = require('swagger-jsdoc');
const express = require('express');
const app = express();

const swaggerOptions = {
    swaggerDefinition: {
        info: {
            title: 'My API',
            description: 'My API description',
            contact: {
                name: 'My API team'
            },
            servers: ['http://localhost:3000']
        }
    },
    apis: ['./routes/*.js']
};

const swaggerDocs = swaggerJSDoc(swaggerOptions);
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocs));

/**
 * @swagger
 * /example:
 *   get:
 *     description: Get example data
 *     parameters:
 *       - name: name
 *         description: User's name
 *         in: query
 *         type: string
 *         required: true
 *     responses:
 *       200:
 *         description: Success
 *       404:
 *         description: Not found
 */
app.get('/example', (req, res) => {
  const name = req.query.name;
  res.send(`Hello, ${name}!`);
});

app.listen(3000, () =>
  console.log('Swagger is running on http://localhost:3000/api-docs')
);

1. 在命令行中运行以下命令，启动服务器：

node app.js

1. 访问以下网址，以查看Swagger UI文档：

http://localhost:3000/api-docs/

在文档中找到“Get example data”部分，点击“Try it Out”按钮，输入“name”参数并点击“Execute”按钮。您应该会在响应中看到“Hello, [name]！”的消息，其中[name]是您输入的名称。