简介 - 安装 - 设置（在 Node.js 中开发）

Created: November-22, 2018

介绍：

Swagger 是一组描述 REST API 的格式的规则/规范。它为代码生成器和编辑器等正式规范提供了强大且积极开发的工具生态系统。Swagger 的最佳部分是将方法，参数和模型的文档紧密集成到服务器代码中，从而使 API 始终保持同步。这是一个链接，简要概述了什么是 swagger：入门。

写作规格：

规范可以用 JSON 或 YAML 编写。因此我们相应地制作了 swagger.json 或 swagger.yaml 文件。在线编辑器可用于创建文件。这是一个描述规范语法的链接： http ： //swagger.io/specification/

使用招摇的方法：

API 优先方法（自上而下方法）： 使用 swagger 编辑器→编写 swagger 定义→使用 swagger-codegen 和 swagger-ui 生成 API
服务优先方法（自下而上方法）： 使用 swagger 注释开发 JAX-RS 资源类→使用 swagger-core 自动生成 swagger 定义→使用 swagger-codegen 和 swagger-ui 生成客户端 API 和文档。以上可以在 swagger maven 插件期间的 maven 构建期间完成。

安装和设置

在本节中，我们将安装 swagger，设置 swagger UI 并使用它生成服务器端和客户端 SDK。要使用 Node 包管理器安装 swagger，请执行以下命令：

npm install -g swagger

使用’-g’标志将确保模块全局安装。接下来，我们将使用以下命令创建项目：

swagger project create <project-name>

这将要求用户选择用于开发 REST API 的框架。Express 可以选择相同的。这将创建项目目录，其中包含以下各项以及每个项目中的 README.md 文件：

API /
- 控制器/
- 助手/
- 嘲笑/
- 昂首阔步/
配置/
测试/
- API /
  - 控制器/
  - 助手
app.js
package.json

服务器现在基本就绪，可以使用此命令在项目根目录中执行：

swagger project start

如果主机服务器设置为 localhost 且未在 app.js 文件中修改端口号，则服务器将在以下位置启动：http://localhost:10010 现在，可以使用 swagger UI 进一步开发 REST API。这可以通过以下方式在新终端中启动：

swagger project edit

这将在随机生成的端口上的浏览器选项卡中打开 swagger 编辑器。可以看到示例 hello GET 请求已存在于 swagger.yaml 文件中。对此文件的任何进一步更改都将导致服务器自行重新启动。

在 paths 部分中，x-swagger-router-controller 使用的值应该是 controllers 文件夹中的 javascript 文件名。作为示例，hello_world.js 应该出现在 controllers 目录中。此外，operationId 参数的值表示上述 javascript 文件中的函数名称。这是应该编写业务逻辑的地方。因此，我们的 swagger 设置已完成，可用于进一步开发我们的 API。