目标：

1.描述Swagger的目的

2.基于使用Node、Express和Postgres开发的现有RESTful API生成Swagger规范

3.设置Swagger UI以测试API并与之交互

介绍：

Swagger 是用于描述、生成、使用、测试和可视化 RESTful API的规范。它提供了许多用于基于给定端点自动生成文档的工具。现在，当您对代码进行更改时，您的文档会更新并与 API 同步，以便消费者可以快速了解哪些资源可用、如何访问它们，以及何时发生的预期（状态代码、内容类型等）与各种端点进行交互。

Swagger是世界上最大的面向OpenAPI规范(OAS)的API开发工具框架，支持跨整个API生命周期的开发，从设计和文档，到测试和部署。

生成Swagger规范：

为了生成Swagger规范，我们将使用swagger-jsdoc。

安装swagger-jsdoc:

npm install swagger-jsdoc@1.3.0 --save

将swagger-jsdoc添加到app.js中：

var swaggerJSOoc=reguire('swagger-jsdoc');

将下面的代码添加到express创建之后：（var app=express();)

 1 // swagger definition
 2 var swaggerDefinition = {
 3   info: {
 4     title: 'Node Swagger API',
 5     version: '1.0.0',
 6     description: 'Demonstrating how to describe a RESTful API with Swagger',
 7   },
 8   host: 'localhost:3000',
 9   basePath: '/',
10 };
11 
12 // options for the swagger docs
13 var options = {
14   // import swaggerDefinitions
15   swaggerDefinition: swaggerDefinition,
16   // path to the API docs
17   apis: ['./routes/*.js'],
18 };
19 
20 // initialize swagger-jsdoc
21 var swaggerSpec = swaggerJSDoc(options);

注意上面的注解。这段代码实际上初始化了Swagger -jsdoc，并将适当的元数据添加到Swagger规范中。

添加路由以提供 Swagger 规范：

1 // serve swagger
2 app.get('/swagger.json', function(req, res) {
3   res.setHeader('Content-Type', 'application/json');
4   res.send(swaggerSpec);
5 });

启动服务器并导航到http://IP:端口/swagger.json以查看基本规范：

{
  "info": {
    "title": "Node Swagger API",
    "version": "1.0.0",
    "description": "Demonstrating how to describe a RESTful API with Swagger"
  },
  "host": "localhost:3000",
  "basePath": "/",
  "swagger": "2.0",
  "paths": { },
  "definitions": { },
  "responses": { },
  "parameters": { },
  "securityDefinitions": { }
}

更新路由处理程序：

swagger-jsdoc 使用JSDoc样式的注释来生成 Swagger 规范。因此，在 YAML 中将此类注释添加到描述其功能的路由处理程序中。

在处理程序上方的/routes/index.js 中添加注释，如下所示：

/**
 * @swagger
 * /api/puppies:
 *   get:
 *     tags:
 *       - Puppies
 *     description: Returns all puppies
 *     produces:
 *       - application/json
 *     responses:
 *       200:
 *         description: An array of puppies
 *         schema:
 *           $ref: '#/definitions/Puppy'
 */
router.get('/api/puppies', db.getAllPuppies);

在之前的代码上方添加以下代码：

/**
 * @swagger
 * definitions:
 *   Puppy:
 *     properties:
 *       name:
 *         type: string
 *       breed:
 *         type: string
 *       age:
 *         type: integer
 *       sex:
 *         type: string
 */

现在我们可以为每个 HTTP 方法使用该定义。

有关更多信息和示例，请参阅Swagger 规范。

get:

/**
 * @swagger
 * /api/puppies/{id}:
 *   get:
 *     tags:
 *       - Puppies
 *     description: Returns a single puppy
 *     produces:
 *       - application/json
 *     parameters:
 *       - name: id
 *         description: Puppy's id
 *         in: path
 *         required: true
 *         type: integer
 *     responses:
 *       200:
 *         description: A single puppy
 *         schema:
 *           $ref: '#/definitions/Puppy'
 */

post:

/**
 * @swagger
 * /api/puppies:
 *   post:
 *     tags:
 *       - Puppies
 *     description: Creates a new puppy
 *     produces:
 *       - application/json
 *     parameters:
 *       - name: puppy
 *         description: Puppy object
 *         in: body
 *         required: true
 *         schema:
 *           $ref: '#/definitions/Puppy'
 *     responses:
 *       200:
 *         description: Successfully created
 */

put:

/**
 * @swagger
 * /api/puppies/{id}:
 *   put:
 *     tags: Puppies
 *     description: Updates a single puppy
 *     produces: application/json
 *     parameters:
 *       name: puppy
 *       in: body
 *       description: Fields for the Puppy resource
 *       schema:
 *         type: array
 *         $ref: '#/definitions/Puppy'
 *     responses:
 *       200:
 *         description: Successfully updated
 */

delete:

/**
 * @swagger
 * /api/puppies/{id}:
 *   delete:
 *     tags:
 *       - Puppies
 *     description: Deletes a single puppy
 *     produces:
 *       - application/json
 *     parameters:
 *       - name: id
 *         description: Puppy's id
 *         in: path
 *         required: true
 *         type: integer
 *     responses:
 *       200:
 *         description: Successfully deleted
 */

添加完成后，在http://IP:端口/swagger.json查看更新的规范。

添加 Swagger UI

最后，下载Swagger UI repo，将下载的repo 中的“dist”文件夹添加到项目目录中的“public”文件夹中，然后将目录重命名为“api-docs”。

现在在“api-docs”目录内的index.html 中只需更新这一行，将：

url = "http://petstore.swagger.io/v2/swagger.json";

改成：

url = "http://localhost:3000/swagger.json";

最后，在浏览器中导航到http://IP:端口/api-docs/以测试 API 端点：