目标：
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 端点：