如何使用 Swagger 文档支持 RESTful API
Swagger 是一种 RESTful API 的文档规范和工具集，可以让前端团队更快速、更简洁地测试和使用 API。本文将介绍如何使用 Swagger 来支持 RESTful API 并生成文档，包括如何在项目中集成 Swagger，定义 API 文档，以及如何在 Swagger 中测试 API。
一、集成 Swagger 到项目中
1.1 安装 Swagger 客户端
在我们的前端项目中，使用 npm 安装 Swagger 客户端：
npm install swagger-jsdoc swagger-ui-express --save-dev
1.2 配置 Swagger 客户端
在我们的项目中，新建一个 swagger.json 文件进行接口文档编写。编写完成后，我们需要在项目中运行 Swagger 并把接口文档展示出来。可以在 app.js 中加入如下代码：
// javascriptcn.com 代码示例
const swaggerJSDoc = require('swagger-jsdoc');
const swaggerUi = require('swagger-ui-express');
const swaggerDefinition = {
info: {
title: '接口文档',
version: '0.0.1',
description: 'API 文档',
},
basePath: '/api',
};
const swaggerSpec = swaggerJSDoc({
swaggerDefinition,
apis: ['./api/*.js'], // 重新指定 swagger.json 的路径
});
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerSpec));这段代码做了如下操作：
- 引入 Swagger 客户端；
- 设置接口文档基本信息；
- 加载 swagger.json 文件；
- 编写接口文档脚本；
- 在 API 目录中写出的接口方法上添加 Swagger 脚本。
二、定义 API 文档
Swagger 仅仅是一个对接口文档的规范，没有什么实体凭据，仅是定义接口文档的格式和结构，我们需要编写符合 Swagger规范的文件，让 Swagger 用它生成文档。在上面 app.js 中使用的 swagger.json 文件，我们会先介绍如何规范性地编写这个文件，并能根据它生成文档。
2.1 什么是 swagger.json
swagger.json 是一个 JSON 文件，我们通过这个文件规范其中的 API 接口，Swagger 通过这个文件能够根据这个文件生成文档，包括 API 的基本信息，请求参数，返回信息等等。
2.2 如何编写 swagger.json
在项目中，可以通过 swagger 库来实现对 swagger.json 规范的编写，可以在项目中安装 Swagger 。Swagger 会允许你创建元数据，通过这个库，你可以检查 API 的生成API 定义的完整性。
在项目中安装之后，你只需要在你的项目中的指定位置，在 api.js 文件中，暴露出需要写的 API 接口就可以生成 API 定义了。这里举个例子：
// javascriptcn.com 代码示例
/**
* @swagger
* /users:
* get:
* tags:
* - users
* description: 列出所有 users
* produces:
* - application/json
* responses:
* 200:
* description: users 列表
* schema:
* type: array
* $ref: '#/definitions/User'
*/
router.get('/users', (req, res) => {
User.findAll().then((users) => {
res.json(users);
});
});这个文件就是在一个 get 请求下，在 /users 路径下写出的 API 接口，同时也有了对应的返回信息。这个写法很简单，但是根据这个结构就能够做到为 API 生成 API 文档，这就是 Swagger 封装的威力。
三、测试 API
在项目集成 Swagger 后，Swagger 可以帮助我们生成接口文档，同时 Swagger 还有一个好玩的功能，就是测试 API。
Swagger 的测试功能非常强大，可以让我们直接与 API 进行对话式交互，测试数据、请求、返回结果等等都会一一现实出来。开发人员可以模拟各种不同条件下的请求。视觉化的测试界面，很容易让我们了解到该如何使用这个神奇的 API。
总结
在使用 Swagger 时，我们要按照一定的规范进行编写，才能使其更好的为我们工作。在项目中，通过引入 Swagger 客户端，定义好 API 文档，集成 Swagger 内部的测试功能，这都有助于我们对我们的接口文档进行高效、精细的管理。所以，我们可以放心使用 Swagger 的这些功能，它们会让我们事半功倍，提高开发、测试效率，让我们专注于编写更好的前端应用。
来源：JavaScript中文网 ，转载请注明来源 本文地址：https://www.javascriptcn.com/post/65483ae67d4982a6eb2829a0