我们都知道记录 API 的重要性。就 Node.js API 而言，无论它们是建立在 Express 之上.js还是任何其他框架之上，您都有很多开源选项。这些包括apiDoc，docbox等。
在本教程中，我们将探索将 Swagger 与 Express.js API 结合使用。Swagger 是一组开源工具，使您能够设计、构建、记录和使用 RESTful Web 服务。它被创建为几乎不可知论，这意味着您可以将其与几乎任何您喜欢的语言和框架一起使用。
在我们的示例中，如何开启Windows 11防篡改安全功能？防止恶意程序关闭防毒软件我们将使用两个库：swagger-ui-express 和 swagger-jsdoc。第一个模块允许您从文件或内联对象提供 Swagger UI（基于 swagger-ui 项目的自动生成视图）。swagger.json
第二个项目是关于在整个代码中使用 JSDoc 如何提升安卓Chrome浏览器下载速度？设置完下载速度可提升3倍注释集成 Swagger。这很有用，尤其是当您拥有广泛的 API 和数十个模型时。
跳跃前进：
-
使用招摇的好处
-
快速.js API 应用程序设置
-
如何将 Swagger 连接到 Node.js
-
创建 API 模型
-
将操作集成到路由中
-
映射端点
-
-
使用 CSS 进行招摇自定义
使用招摇的好处
在我们进入 Swagger 集成到您的 Node.js 应用程序之前，让我们来看看为什么 Swagger 对任何应用程序都很重要——它在开发过程中是如何帮助的。
Swagger 的一个显著好处是，它有助于了解 API 如何为应用程序的客户端工作。Swagger 在应用程序的客户端和服务器端之间同步 API。这样，在前端工作的开发人员可以了解 API 的工作原理并将 API 集成到客户端。
使用 Swagger 的另一个好处是它对开发人员和非开发人员都很全面。参与产品开发的每个人（包括产品经理、利益相关者和开发人员）都可电脑系统运行速度变慢怎么办？设置可提高性能加速你的PC运转！以在 UI 中试用 API，而无需独立运行服务器。
我们可以随心所欲地如何将视频转换为AI动漫？真人视频秒变动画视频自定义 API 文档。因此，总而言之，Swagger的主要优势在于它使API开发过程更快，更高效。
现在，我们知道在应用程序中使用 Swagger 的优势，让我们看看在应用程序中设置和配置它。
快速.js API 应用程序设置
本教程不会涵盖与快速 API 构建相关的任何内容。我们已经有一个现成的示例，您可以在实施之前将其克隆到本地计算机。
这是一个简单的 API，允许您管理内存中的书籍列表。随意使用您的自定义来增加它。
在您的应用程序中安装此功能后，请在终端中运行以下命令：
npm install npm i swagger-ui-express swagger-jsdoc
这些将把所需的依赖项下载到您的应用程序中。现在是时候将 Swagger 集成到您的 Node.js 应用程序中了。
如何将 Swagger 连接到 Node.js
要将 Swagger 连接到 Node.js 应用程序，无线路由器wifi限速怎么设置？路由器用的人太多网速变慢怎么办请导入并在 ：swagger-ui-expressswagger-jsdocserver.js
const express = require("express"),
bodyParser = require("body-parser"),
swaggerJsdoc = require("swagger-jsdoc"),
swaggerUi = require("swagger-ui-express");
这两个对象分别代表我们导入的库。接下来，在应用函数之前添加以下代码：listen
const options = {
definition: {
openapi: "3.1.0",
info: {
title: "LogRocket Express API with Swagger",
version: "0.1.0",
description:
"This is a simple CRUD API application made with Express and documented with Swagger",
license: {
name: "MIT",
url: "https://spdx.org/licenses/MIT.html",
},
contact: {
name: "LogRocket",
url: "https://logrocket.com",
email: "[email protected]",
},
},
servers: [
{
url: "http://localhost:3000",
},
],
},
apis: ["./routes/*.js"],
};
const specs = swaggerJsdoc(options);
app.use(
"/api-docs",
swaggerUi.serve,
swaggerUi.setup(specs)
);
如第一行所示，此配置对象将 OpenAPI 设置为 v3.1.0。
Swagger使用Open API规范，这是一个标准的，与语言无关的RESTful API接口，允许人类和机器了解Web服务的功能，而无需访问源代码或检查网络流量。
您可以参考官方文档了解每个版本的所有可用设置。在这里，我们只使用基础知识：API 信息、名称、标题、描述、许可证、API 所有者的联系方式等。
API 的属性是必不可少的，因为它搜索模型和终结点定义，因此请正确通知它。
最后，我们使用该函数扫描作为参数传入的选项，并返回转换后的 Swagger 规范对象。反过来，这个可以与设置过程一起使用。swaggerJsdoc``swaggerUi
您现在可以通过命令启动应用程序。访问 URL 时，您将看到以下屏幕：npm start``http://localhost:3000/api-docs/
请注意，我们仍然没有在规范中定义任何操作。发生这种情况是因为我们需要将这些操作显式映射到路由。否则，Swagger 无法自行找出 API 端点。
（可选）您可以向 UI 添加搜索栏，以防 API 具有太多操作。为此，请将实现更改为以下内容：
app.use(
"/api-docs",
swaggerUi.serve,
swaggerUi.setup(specs, { explorer: true })
);
现在，搜索栏将显示：
创建 API 模型
与许多重要的框架和 API 架构一样，数据被封装到模型中，以便于访问。Swagger 还希望您的 API 具有模型并让您定义它们。
转到并将以下代码放在文件的开头：routes/books.js
/** * @swagger * components: * schemas: * Book: * type: object * required: * - title * - author * - finished * properties: * id: * type: string * description: The auto-generated id of the book * title: * type: string * description: The title of your book * author: * type: string * description: The book author * finished: * type: boolean * description: Whether you have finished reading the book * createdAt: * type: string * format: date * description: The date the book was added * example: * id: d5fE_asz * title: The New Turing Omnibus * author: Alexander K. Dewdney * finished: false * createdAt: 2020-03-10T04:05:06.157Z */
还记得我们讨论过的 JSDocs 吗？JSDocs 现在进入了场景，并通过注释帮助我们设置其余的 Swagger 规范定义。在这里，您可以根据需要定义任意数量的架构。在我们的例子中，我们只是定义域。@swagger``Books
必需属性接收必须在请求中填写的属性列表。此步骤对于让人们知道在使用您的 API 时必须发送的内容至关重要。
该属性描述有关模型属性的详细信息。每个属性都必须有一个名称，后跟其类型、描述（可选）和格式（您也可以验证值）。有关可用数据类型的完整列表，请参阅 Swagger 数据类型。properties
最后，您可以为此架构模型提供请求数据的示例。这在以后会很有用。当您重新启动应用程序并刷新页面时，您将看到以下屏幕：
好多了，不是吗？
请务必注意，如果在架构中遇到 ，请确保检查 YAML 配置中的缩进：YAMLSemanticError
将操作集成到路由中
现在，我们已将Swagger集成到路线中。但是，我们仍然没有任何操作。让我们解决这个问题。在上一个 JSDoc 注释之后，添加以下内容：schema
/** * @swagger * tags: * name: Books * description: The books managing API * /books: * post: * summary: Create a new book * tags: [Books] * requestBody: * required: true * content: * application/json: * schema: * $ref: '#/components/schemas/Book' * responses: * 200: * description: The created book. * content: * application/json: * schema: * $ref: '#/components/schemas/Book' * 500: * description: Some server error * */
让我们从 Swagger 标签开始部分分析它。标签允许您在 Swagger 文档中创建一个部分。分配给此标记的所有路由将显示在同一分区下。这是一个组织环境。
在我们的示例中，所有终端节点都将映射到同一标记。接下来，我们设置了第一条路线：这本书的创作。这很简单。首先，定义 a 并指定路径将附加到的路径。title``tag
然后，我们有请求和响应。在请求中，定义三项内容：请求是否必需、请求的内容类型以及必须从中处理请求的架构。
可以通过 Swagger 运算符引用架构。对于响应，请定义 HTTP 响应代码以及每个响应代码的属性。我们只是担心有.#components/schemas``HTTP 200
继续并直接在 Swagger UI 页面中测试新操作：
现在，您可以看到示例值发生的位置。为用户提供示例数据作为他们想要执行操作时的参考会更容易。
您可以在下面找到所有其他操作的代码：
/**
* @swagger
* tags:
* name: Books
* description: The books managing API
* /books:
* get:
* summary: Lists all the books
* tags: [Books]
* responses:
* 200:
* description: The list of the books
* content:
* application/json:
* schema:
* type: array
* items:
* $ref: '#/components/schemas/Book'
* post:
* summary: Create a new book
* tags: [Books]
* requestBody:
* required: true
* content:
* application/json:
* schema:
* $ref: '#/components/schemas/Book'
* responses:
* 200:
* description: The created book.
* content:
* application/json:
* schema:
* $ref: '#/components/schemas/Book'
* 500:
* description: Some server error
* /books/{id}:
* get:
* summary: Get the book by id
* tags: [Books]
* parameters:
* - in: path
* name: id
* schema:
* type: string
* required: true
* description: The book id
* responses:
* 200:
* description: The book response by id
* contens:
* application/json:
* schema:
* $ref: '#/components/schemas/Book'
* 404:
* description: The book was not found
* put:
* summary: Update the book by the id
* tags: [Books]
* parameters:
* - in: path
* name: id
* schema:
* type: string
* required: true
* description: The book id
* requestBody:
* required: true
* content:
* application/json:
* schema:
* $ref: '#/components/schemas/Book'
* responses:
* 200:
* description: The book was updated
* content:
* application/json:
* schema:
* $ref: '#/components/schemas/Book'
* 404:
* description: The book was not found
* 500:
* description: Some error happened
* delete:
* summary: Remove the book by id
* tags: [Books]
* parameters:
* - in: path
* name: id
* schema:
* type: string
* required: true
* description: The book id
*
* responses:
* 200:
* description: The book was deleted
* 404:
* description: The book was not found
*/
理想情况下，这些映射应放置在每个 Express.js 路由函数的上方。但是，为了简单起见，我们将它们集中在一个地方。
映射端点
现在，我们将操作分为两个主要类别：接收参数的操作和不接收参数的操作。这对于 Swagger 了解如何将路由与正确的路径参数匹配是必要的。id
每当终结点中有参数时，无论其类型如何，都必须通知属性下的详细信息。parameters
以下是正确映射所有终结点的结果：
使用 CSS 进行招摇自定义
您可以通过在 Swagger 集成中实现自定义 CSS 来自定义 Swagger UI。为此，请将选项添加到 ：customCssUrl``swaggerUi.setup
app.use(
"/api-docs",
swaggerUi.serve,
swaggerUi.setup(specs, {
explorer: true,
customCssUrl:
"https://cdn.jsdelivr.net/npm/[email protected]/themes/3.x/theme-newspaper.css",
})
);
在这里，我们将自定义 CSS 文件传递给选项。它将使用自定义样式更改 Swagger UI。customCssUrl
以下是自定义 CSS 文件之前的外观：
现在，看看之后它会是什么样子：
结论
您可以单独测试每个端点，以确保它完全按照您的邮递员请求工作。
Swagger 能够做的不仅仅是记录您的 API。快速阅读官方文档将使您更好地了解其功能。请记住，记录应该是团队文化的一部分。否则，您的文档不会始终是最新的。