如何使用Insomnia为您的RESTAPI创建文档

作者选择了 COVID-19 Relief Fund 作为 Write for DOnations 计划的一部分来接受捐赠。

介绍

在本教程中，您将使用 OpenAPI 规范 (v3) 记录您的 API。 OpenAPI 文件是遵循 OpenAPI 规范 的 JSON 或 YAML 文件。 该规范定义了您的 JSON/YAML 文件必须包含哪些字段，以及它将如何反映在您将用于托管它的文档服务中。 许多服务支持 OpenAPI，因此您可以选择甚至使用多个服务，而无需更改 API 文档的格式。

要创建文档，您将使用 Insomnia，这是一个免费的 开源 应用程序，它允许您测试您的 API 并通过实时并行设计文档 -侧面预览。 Insomnia 不支持 JSON，但它确实使编写 YAML 变得容易。 YAML 是 API 文档的不错选择，因为这些文档可能会变得非常大，而 JSON 文档会变得混乱且难以阅读。

最后，您将使用 Redoc 托管 API 文档，这是许多公司使用的 开源 应用程序。 Redoc 获取您生成的 OpenAPI 文档，并为您提供一个 HTML 页面，该页面显示了一个漂亮的交互式文档版本。 您还将 Redoc 生成的站点部署到 GitHub Pages，这是 GitHub 提供的免费网站托管解决方案。

在本教程中，您将了解有关 OpenAPI 的更多信息，根据 Insomnia 中的 OpenAPI 规范记录您的 API，并使用 Redoc 在 GitHub Pages 上托管此文档。

先决条件

要遵循本教程，您将需要：

• 用于记录的 REST API。 如果您想创建自己的，可以查看 DigitalOcean 社区站点以获取一些 教程。 本教程将使用 JSON 占位符 API。
• Insomnia 已下载并安装在您的本地计算机上。
• NodeJS v12 或更高版本 安装在本地计算机上。
• 熟悉 YAML，您可以从 文档 中获得。
• 有后端 Web 开发经验，您可以从 MDN Web Docs 中获得。
• 为该项目创建的 GitHub 帐户和 新存储库 。 您可以按照 GitHub 的快速入门指南 创建新的 GitHub 存储库 来创建新的存储库。 您还需要安装 git cli 工具 ，以便推送到 GitHub。

第 1 步 — 了解您的 API

在此步骤中，您将记下您的 API 接受的路由及其相关参数和响应。 由于您将为其他人记录 API，并且由于您将来可能还会参考此文档，因此请务必注意您需要记录的所有内容。 OpenAPI 允许您为每个 API 路由定义请求正文、标头、cookie 甚至可能的响应。

本教程将使用 JSON 占位符 API，这是一个免费的模拟 API。 由于这个 API 非常大，您将只记录本教程中的 /posts 部分。

下表显示了您将在本教程中记录的五条路线中的每条路线的方法、路线路径和描述。 制作表格或类似的东西很有帮助，这样您就不会忘记任何路线（如果 API 很大，可能会发生这种情况）。

方法	路线	描述
得到	/posts	获取所有帖子
得到	/posts/:id	获取单个帖子
邮政	/posts	创建帖子
放置/补丁	/posts/:id	更新帖子
删除	/posts/:id	删除帖子

现在您知道您的 API 可以做什么，是时候开始使用 Insomnia 记录它了。

第 2 步 - 创建一个失眠项目

在这一步中，您将创建一个 Insomnia 项目。 Insomnia 项目包含 OpenAPI 文档、您为 API 编写的任何测试以及您创建的任何请求。 该界面分为三个选项卡：Design、Test和Debug。 您将专注于本教程的设计选项卡。

打开 Insomnia 应用程序并转到您的仪表板。 通过单击 Insomnia 窗口右上角的 Create 按钮创建一个新的 Design Document 并为其命名。 对于本教程，您可以使用 json-placeholder-docs.yaml。

注意： YAML 在设计上只接受空格作为缩进。 然而，Insomnia 默认使用制表符缩进。 这将在以后的更新中修复，但现在，通过单击右上角的齿轮图标或按 Ctrl/Cmd + , 打开您的 Preferences。 在 Font 部分，取消选中 Indent with Tabs 并关闭 Preferences 窗口。 这将使 Insomnia 使用空格而不是制表符。

您现在应该看到三个窗格，如下面的屏幕截图所示。 第一个窗格显示您的文档的概述，例如您的 API 的路由和您定义的组件（稍后您将了解有关这些的更多信息）。 中间窗格包含您将用于在 YAML 中编写 OpenAPI 文档的代码编辑器。 此编辑器还会自动检测错误并在底部通知您。 最后，右侧的最后一个窗格是文档的实时预览。 您会看到一个错误，因为您仍然需要告诉 Insomnia 您将使用哪个版本的 OpenAPI。

在设计选项卡的代码编辑器中，添加以下行：openapi: 3.0.3。 这表示您将使用的 OpenAPI 规范的版本。 在撰写本文时，最新版本是 3.0.3。 如果您愿意，请随时将其更改为更高版本。

您的屏幕应与此类似：

现在您已经熟悉了 Insomnia 界面，您可以开始编写文档了。

第 3 步 — OpenAPI 规范入门

在此步骤中，您将了解有关 OpenAPI 规范的更多信息。 API 规范可以是 JSON 或 YAML 文件，但 Insomnia 仅支持 YAML。 它应该有一个名为 openapi 的键，用于指定您正在使用的 OpenAPI 规范的版本。

根据 规范 ，以下是可以出现在文档根目录的字段：

姓名	类型	描述
openapi	string	需要 。 OpenAPI 架构的版本。
info	信息对象	需要 。 包含有关 API 信息的对象。
servers	服务器对象数组	一个数组，其中包含为 API 服务器提供连接选项的对象。
paths	路径对象	需要 。 一个对象，包含 API 提供的路由、方法、请求体、参数和响应。 这是文件中最重要的部分。
components	组件对象	包含可重复使用的组件，旨在减少文件大小并保持文档清洁。
security	安全对象数组	包含 API 的身份验证机制列表。 超出了本教程的范围。
externalDocs	外部文档对象	包含 API 的任何外部文档

如果这太多了，请不要担心。 您将深入研究每个属性，除了 security，因为这超出了本教程的范围。 security 字段定义路由的身份验证方法（例如，用户名/密码、JSON Web Token 或 oauth），但 JSONPlaceholder 没有任何身份验证功能.

第 4 步 — 添加 info 对象

在此步骤中，您将使用步骤 1 中的表格开始使用 Insomnia 编写 API 文档。 您将从 info 对象开始。

info 对象包含有关您正在记录的 API 的信息。 这包括 API 的 title、version、API 的 description、到其知识库的链接 (documentation) 及其条款-服务（tos）。

根据规范，info object 应该是这样的：

姓名	类型	描述
title	string	需要 。 API 的标题。
description	string	API 的简短描述。 Markdown 可以在这里使用。
termsOfService	string	API 服务条款的 URL。
contact	接触对象	公开 API 的联系信息。
license	许可对象	公开 API 的许可信息。
version	string	需要 。 文档的版本，而不是 OpenAPI 规范。

info 字段有两个必填属性：文档的 title 和文档的 version，它们应该与您的 API 应用程序的版本相同。 其他字段用于通知用户您的 API。

现在，您将使用三个最常用的字段将 info 对象添加到文档中：title、description 和 version。 在 Insomnia 应用程序中，将以下 YAML 代码添加到 Design 选项卡编辑器：

info:
  title: JSONPlaceholder
  description: Free fake API for testing and prototyping.
  version: 0.1.0

这是一个随机版本号，因为 JSONPlaceholder 不公开版本号。 按照上一步的规范，随意将任何其他字段添加到 info 对象。

警告： YAML 对缩进非常挑剔。 它必须用空格缩进，并且缩进大小必须在整个文档中保持一致。

现在您已经添加了包含 API 基本信息的 info 对象，您将添加下一个对象：externalDocs。

第 5 步 — 添加 externalDocs 对象

在此步骤中，您将添加 externalDocs 对象。 此对象包含指向 API 可能拥有的任何其他文档的链接。 OpenAPI 文档仅定义您的 API 具有的任何路由及其参数和响应，因此通常用作参考。 建议包含单独的人工生成的文档来解释每个操作并指导用户。 在 JSONPlaceholder 的情况下，有一个 指南 。

根据规范，externalDocs 对象 应该如下所示：

字段名称	类型	描述
description	string	目标文档的简短描述。 可以使用降价。
url	string	需要 。 目标文档的 URL。

在您的 YAML 文档中，添加一个指向 JSONPlaceholder 指南的 externalDocs 对象：

externalDocs:
  description: "JSONPlaceholder's guide"
  url: https://jsonplaceholder.typicode.com/guide

您应该会在 Insomnia 右侧的预览窗格中看到更改。

您现在已链接到 API 的外部文档。 接下来，您将添加 servers 数组。

第 6 步 — 添加 servers 数组

在此步骤中，您将添加 servers 数组，其中包含将托管 API 的所有 URL。 您创建的文档将托管在与占位符 API 不同的域上（也就是说，您的文档不会托管在 jsonplaceholder.typicode.com 上）。 因此，您无法隐式获取 Insomnia 预览中显示的 API 路由旁边的 Try It Out 按钮的 URL。

为了解决这个问题，OpenAPI 提供了一个 servers 字段。 将以下行添加到您的 YAML 文档中：

servers:
- url: https://jsonplaceholder.typicode.com
  description: JSONPlaceholder

有了它，您现在可以调用 API。

第 7 步 — 添加 paths 对象

在这一步中，您将添加 paths 对象，它是文档的核心。 此对象包含 API 提供的所有路由。 它还包含任何参数、方法、请求正文和路由的所有响应。

路径对象的每个键都是一个路由 (/posts)，值是 Path Item 对象。

根据 OpenAPI 规范，Path Item object 看起来像这样：

姓名	类型	描述
summary	string	此路线的可选摘要。
description	string	路由可以做什么的可选描述。
get/post/put/patch/delete等	操作对象	此路由上的操作（方法）的定义。
servers	服务器对象数组	一个替代的 server 数组来服务这个路径中的所有操作。
parameters	参数对象的数组	适用于此路径上所有操作的参数。 这些参数可以在查询字符串、标头、cookie 或路径本身上。

Path Item 对象有许多字段。 顾名思义，summary 和 description 字段提供了路径的简短摘要和较长的描述。 servers 对象与主 OpenAPI 文档中的对象相同。 它定义了替代服务器。 parameters 对象定义该路径的任何路径或查询参数。 每个 Path Item 对象都可以有一个 操作 对象。 operation 对象记录了可用于此 API 路由的 HTTP 方法。

operation 对象有 很多项，但在本教程中，您将专注于较小的集合：

姓名	类型	描述
tags	strings 的数组	API 文档控制的标签列表。 标签可用于对相似的路由进行分组。
summary	string	操作的简短摘要。
description	string	操作说明。 Markdown 可以在这里使用。
externalDocs	外部文档对象	此操作的其他外部文档。 与主对象上的 externalDocs 相同。
parameters	参数对象数组	与 Path Item 对象中的 parameters 相同。
requestBody	请求正文对象	请求的正文。 当方法 GET 或 DELETE 时不能使用。
responses	响应对象	需要 。 API 针对此操作返回的可能响应列表。

tags 属性对相似的路径进行分组。 具有相同标签的路径最终将归为一组。 summary 和 description 字段与 path 对象中的字段相同。 它们允许您分别添加简短的摘要和较长的描述。 externalDocs 属性与主文档中的属性相同：它允许您为该操作定义任何外部文档。

parameters 对象与 path 对象中的对象相同。 它允许您定义必须与请求一起发送的路径、查询、标头或 cookie 参数。 requestBody 还允许您定义参数，但在请求的正文中。 此 requestBody 字段仅在 POST、PUT 和 PATCH 请求中可用，如 HTTP/1.1 协议 RFC7231 中所定义.

/posts 路线

现在，您将通过在 paths 对象中创建一个对象来记录 API 路由。 首先，您将记录 /posts 路线。 首先将这些行添加到您的 YAML 文档中：

paths:
  "/posts":

笔记： /posts is in quotes because it contains special symbols (/). This is required by YAML so it doesn’t misinterpret the line.

接下来，您需要添加一个字段，其键是 HTTP 方法，值是 Path Item 对象。 通过添加突出显示的行来记录 GET /posts 路由，该路由返回所有帖子的数组：

paths:
  "/posts":
    get:
      tags: ["posts"]
      summary: Returns all posts.

tags 字段将相似的操作组合在一起。 （注意预览中的手风琴如何被称为 posts。）

接下来，记录可以返回的响应。 您将从该 API 获得的唯一响应是 200 响应，其中包含所有帖子的数组。

JSONPlaceholder 可以返回的示例帖子如下所示：

{
  "userId": 1,
  "id": 1,
  "title": "A post's title",
  "body": "The post's content"
}

由于您将经常重用它，因此您可以为这篇文章创建一个可重用的组件。 这可以使用 组件对象 来完成。 您可以将 post 定义为 schemas 对象中的模式，该对象将位于 components 对象中。 此架构类似于 JSON 架构 文件中的架构。

将发布模式添加到您的 YAML 文件中。 请注意，components 对象必须放在文档的根目录中（没有任何缩进），而不是在 paths 对象中。

components:
  schemas:
    post:
      type: object
      properties:
        id:
          type: number
          description: ID of the post
        title:
          type: string
          description: Title of the post
        body:
          type: string
          description: Body of the post
        userId:
          type: number
          description: ID of the user who created the post

上面的模式是一个 object，用 type: object 表示。 它有四个properties：id、title、body和userId。 这就是定义模式的方式。 现在您可以在任何对象中使用 $ref 来引用此架构。 这是根据 URI 语法规范 RFC3986 定义的。

现在您有了架构，您可以添加 responses 对象。 该对象具有其值为返回的状态码或default的项，以捕获所有其他状态，并且值为响应对象。 此对象包含响应的 description、返回的任何 headers 和 响应体 ，以及 content 对象。

通过复制突出显示的行，将 responses 对象添加到 /posts 路径的 get 操作中：

paths:
  "/posts":
    get:
      tags: ["posts"]
      summary: Returns all posts.
      <$>responses:<$>
        <$>"200":<$> # 200 Status Code
          <$>description:<$> All went well
          <$>content:<$>
            <$>application/json:<$> # Reponse is returned in JSON
              <$>schema:<$>

请务必将 200 括在引号中，使其成为字符串而不是数字。

在这里，您定义了一个返回的响应，该响应带有 200 状态码，并且具有 application/json 的 Content-Type 标头。 在这个 schema 对象中，您需要传递对刚刚创建的 post 模式的引用。 这可以通过 $ref 来完成。

除了 schema 之外，application/json 对象还可以包含您希望提供的任何 examples。

现在，在 schema 中添加对 post 模式的引用。

$ref: "#/components/schemas/post"

# 指的是文档的根。 由于 post 模式位于 components/schemas/post 中，所以你应该这样写。 由于 # 是 YAML 中的保留符号，因此您需要将 ref 括在引号中。

您的 Insomnia Design 选项卡应如下所示：

您可以看到 insomnia 已经呈现了您的文档的预览。 /posts 路由已被分组到 posts 部分，因为标签，并且正确的响应也会显示，正如您在架构中定义的那样。 您定义的相同内容类型和您定义的相同架构将在右侧预览。

您可以尝试更改某些内容，例如路径的 tag 或 responses，并查看它的实时更新。 完成后一定要改回来。

注意：在预览的Path操作中按Try It Out按钮，然后按Execute按钮调用JSONPlaceholder API并接收响应。

记录了 GET 路线后，是时候记录 POST /posts 路线了。 这将与之前的操作非常相似，但这次将是一个 POST 请求，因此对象的键是 post（在下面突出显示）。 将以下行添加到您的 YAML 文件中：

paths:
  "/posts":
    # ...
    <$>post<$>:
      tags: ["posts"]
      summary: Create a new post
      responses:
        "200":
          description: A post was created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/post"

您刚刚定义了另一个操作。 这一次，它是一个 POST 请求，具有相同的 tag，因此它与您之前定义的 GET 请求一起分组。 响应也具有相同的模式，因为这将由 JSONPlaceHolder 返回。

仍然缺少一件事：post 方法也接受请求正文。 它还没有被记录，所以将 requestBody 对象添加到 post 操作中。 请求正文类似于 response 对象。 有一个 description 和 content 字段，与 response 对象相同，还有一个 required 字段，它是一个布尔值。 此字段控制此请求是否需要正文。 在这种情况下，它是，因此将 requestBody 对象添加到您的操作中。

paths:
  "/posts":
    # ...
    <$>post<$>:
      tags: ["posts"]
      summary: Create a new post
      <$>requestBody:<$>
    <$>content:<$>
      <$>application/json:<$>
        <$>schema:<$>
          <$>$ref: "#/components/schemas/post"<$>
    <$>required: true<$>
      responses:
        "200":
          description: A post was created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/post"

此时，您的 paths 对象应如下所示：

paths:
  "/posts":
    get:
      tags: ["posts"]
      summary: Returns all posts
      responses:
        "200":
          description: All went well
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/post"
    post:
      tags: ["posts"]
      summary: Create a new post
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/post"
        required: true
      responses:
        "200":
          description: A post was created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/post"

在本节中，您记录了 /posts 路由中可用的 GET 和 POST 操作。 接下来，您将记录 /posts/:id 路由，用于读取、修改或删除单个帖子。

/posts/:id 路线

接下来，您将记录 /posts/:id 路线。 这条路线有三个操作：GET、PUT和DELETE。 他们得到一个帖子，更新一个帖子，然后删除一个帖子。 :id是动态参数，可以是数字（例如：/posts/1、/posts/2等）。 在 OpenAPI 中，这表示为 {id}，如下例所示：

paths:
  "/posts":
  # ...
  "/posts/{id}":
  # TODO

in 属性定义了参数的放置位置。 这可以在 query 字符串中，在 cookie 中，在 header 中，或者作为 path 本身的一部分。 description 是参数的描述。 required 字段是一个布尔值，指示是否需要该参数。 在 path 参数的情况下，required 必须是 true，因为参数是路径本身的一部分。

路径参数是特殊的，所以它们在路径中使用大括号 ({}) 定义。 参数的名称包含在大括号中，并且必须与 name 字段中的名称匹配。 首先，您需要将 id 定义为 parameters 数组中的参数对象。 以下是你将如何做到的：

paths:
  "/posts/{id}":
    parameters:
    - name: id # Must be same as the value in the {}.
      in: path
      description: ID of the post
      # Since this is in the path, the parameter HAS to be required
      required: true
      # Defining the type of the parameter
      schema:
        # In this case, it is just a string
        type: string

请务必包含连字符 (-)，否则 parameters 数组将成为对象

最后要记录的是操作及其响应和请求主体（如果有的话）。 这与您在上一节中所做的类似。

首先，添加 GET /posts/:id 操作，得到一个帖子。

get:
  tags: ["post"]
  summary: Get a single post
  responses:
    "200":
      description: All went well
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/post"
    "404":
      description: Post not found
      content:
        application/json:
          schema:
            type: object
            properties: {}

请注意，这一次，有一个 404 响应。 这是因为如果找不到帖子，GET 请求可能会返回 404 错误。 上面代码中的 properties: {} 是您在 YAML 中定义空对象的方式。

接下来，添加 PUT /posts/:id 操作，更新帖子。 此方法结合了上述 GET 和 POST 方法，因为它同时具有 requestBody 和 404 响应。

put:
  tags: ["post"]
  summary: Update a post
  requestBody:
    content:
      application/json:
        schema:
          $ref: "#/components/schemas/post"
    required: true
  responses:
    "200":
      description: All went well
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/post"
    "404":
      description: Post not found
      content:
        application/json:
          schema:
            type: object
            properties: {}

JSONPlaceholder 并没有真正验证您发送的数据，因此没有 400 或 422 响应，但如果您正在记录的 API 做了类似的事情（它应该），是一定要记录这些响应。 为避免重复，您可以创建 response components，就像在上一节中所做的那样。

最后，添加 DELETE /posts/:id 操作，删除帖子。 这与 GET 方法相同，因为它返回一个 404，但这次的操作是 delete。

delete:
  tags: ["post"]
  summary: Delete a post
  responses:
    "200":
      description: All went well
      content:
        application/json:
          schema:
            type: object
            properties: {}
    "404":
      description: Post not found
      content:
        application/json:
          schema:
            type: object
            properties: {}

请注意，DELETE 方法仅返回一个空对象 ({})，即使在 200 响应中也是如此。

至此，您已经成功记录了 JSONPlaceholder 的 /posts 路线。 这是完整的 YAML 文档。

openapi: 3.0.3

info:
  title: JSONPlaceholder
  description: Free fake API for testing and prototyping.
  version: 0.1.0

externalDocs:
  description: "JSONPlaceholder's guide"
  url: https://jsonplaceholder.typicode.com/guide

servers:
- url: https://jsonplaceholder.typicode.com
  description: JSONPlaceholder

paths:
  "/posts":
    get:
      tags: ["posts"]
      summary: Returns all posts
      responses:
        "200":
          description: All went well
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/post"
    post:
      tags: ["posts"]
      summary: Create a new post
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/post"
        required: true
      responses:
        "200":
          description: A post was created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/post"
  "/posts/{id}":
    parameters:
    - name: id # Must be same as the value in the {}.
      # Location of the parameter.
      # Can be `path`, `cookie`, `query` or `header`
      in: path
      description: ID of the post
      # Since this is in the path, the parameter HAS to be required
      required: true
      # Defining the type of the parameter
      schema:
        # In this case, it is just a string
        type: string
    get:
      tags: ["post"]
      summary: Get a single post
      responses:
        "200":
          description: All went well
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/post"
        # But this time, you can also get a 404 response,
        # which is an empty JSON object.
        "404":
          description: Post not found
          content:
            application/json:
              schema:
                type: object
                properties: {}
    put:
      tags: ["post"]
      summary: Update a post
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/post"
        required: true
      responses:
        "200":
          description: All went well
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/post"
        "404":
          description: Post not found
          content:
            application/json:
              schema:
                type: object
                properties: {}
    delete:
      tags: ["post"]
      summary: Delete a post
      responses:
        "200":
          description: All went well
          content:
            application/json:
              schema:
                type: object
                properties: {}
        # But this time, you can also get a 404 response,
        # which is an empty JSON object.
        "404":
          description: Post not found
          content:
            application/json:
              schema:
                type: object
                properties: {}

components:
  schemas:
    post:
      type: object
      properties:
        id:
          type: number
          description: ID of the post
        title:
          type: string
          description: Title of the post
        body:
          type: string
          description: Body of the post
        userId:
          type: number
          description: ID of the user who created the post

在上面的文档中，您记录了 JSONPlaceholder 提供的所有 /posts 路由，并且还介绍了所有受支持的 HTTP 方法。 您还了解了参数、请求正文和不同的响应。

完成 OpenAPI 文档后，下一步就是将其提供给用户。

第 8 步 — 使用 Redoc 显示 API 文档

虽然 Insomnia 确实有一个漂亮的预览窗格，但您不能指望所有用户都安装了 Insomnia，因此您将使用 Redoc 以一种易于阅读的方式显示 OpenAPI YAML 文件。

要构建 Redoc，您需要安装 NodeJS。 （请注意，您无需了解任何 NodeJS 或 JavaScript 即可构建 Redoc。）

在计算机上的任何位置创建一个新文件夹。 您将在此文件夹中构建 Redoc 并将其部署到 GitHub。

首先，您需要将当前的 OpenAPI 文档保存到此文件夹。 在当前文件夹中创建一个名为 openapi.yaml 的新文件，并将 Insomnia 的设计选项卡中的内容复制粘贴到该文件中。 Redoc 现在可以使用此文件来生成您的 API 文档

接下来，在该文件夹中打开一个终端并运行以下命令来构建 Redoc。

npx redoc-cli --output index.html bundle openapi.yaml

npx 是 NPM（节点包管理器）' 的 CLI 工具，用于获取 CLI 可安装包并运行它。 这允许您运行 redoc-cli 而无需将其实际安装到全局 $PATH。 相反，它将通过 npx 提供。 如果询问是否安装 redoc-cli，请务必输入 y。 接下来，您要告诉 Redoc 到 bundle 刚刚创建的 openapi.yaml 文件到一个零依赖的 HTML 文件中，在这种情况下，它将是 index.html，因为您通过了--output 标志。

这应该在该目录中创建一个名为 index.html 的新文件。 该文件是文档，由 Redoc 提供支持。 在浏览器中打开文件并检查它以确保您定义的每条路线都被覆盖。

现在您已经生成了文档站点，是时候使用 GitHub Pages 将其提供给其他人了。

第 9 步 — 部署到 GitHub 页面

现在您已经有了一个文档网站，您可以使用 GitHub Pages 来部署它，让全世界都能看到。 作为先决条件的一部分，您创建了一个 新的 GitHub 存储库 。 复制 Quick Setup 中显示的克隆 URL。 您将使用 git 命令 将 openapi.yaml 和 index.html 文件推送到 GitHub。 请务必在包含这两个文件的文件夹中运行以下命令。

首先，您将初始化 git 存储库并提交所有文件：

git init
git add .
git commit -m "First commit" # Feel free to change this message

接下来，您将把更改部署到 GitHub。 首先，您需要告诉 git 您的 GitHub 存储库应该是远程存储库。 远程存储库通常存储在名称 origin 下。

git remote add origin YOUR_GITHUB_REPO_URL

最后，使用以下命令将您的更改推送到 GitHub：

git push origin main

注意： Git 已将默认分支的名称从 master 更改为 main，因此在上面的命令中使用了 main。 如果您愿意，请随意将 main 替换为 master。

刷新 GitHub，你应该在那里看到你的两个文件。

现在您需要启用 GitHub Pages。 转到存储库的设置，然后单击 侧边栏 上的 Pages 按钮。 将源分支更改为您的默认分支（通常为 main 或 master），将文件夹更改为 / (root)，然后单击 保存。

最后，访问 https://your_username.github.io/your_repo_name，您应该会看到刚刚创建的 Redoc 页面。 你可以在这里查看我发布到GitHub Pages的版本。

这样，任何人都可以通过上面的 URL 查看您的 API。

结论

在本教程中，您记录了 JSONPlaceholder API 的 /posts 路由。 您记录了路径参数以及请求正文和可能的响应。 您还学会了使用可重用组件来减少样板文件。 随意查看源代码和live版本。

作为下一步，尝试记录 JSONPlaceholder 提供的其他路由（例如，/users），或者使用您自己的 API 尝试一下。 您可以从这里开始，使用 Docasaurus 等工具添加解释和指导用户的文档。 请记住保留您的 API Spec DRY 并且易于阅读，以便您将来可以对其进行更改。 Insomnia 还具有其他功能，例如测试和调试 API 的能力，因此请务必通过 阅读文档 来检查这些功能。