文档

页面摘要： 文档插件通过扫描内容类型和路由，为你的 API 自动生成 OpenAPI/Swagger 文档。本文档将引导你完成安装、自定义设置以及限制对文档的访问。

文档插件自动创建你的 API 文档。它本质上会生成一个 swagger 文件，并遵循 Open API 规范版本。

• 位置：可通过管理面板使用。 可通过管理面板和服务器代码进行配置，两者拥有一组不同的选项。
• 包名：@strapi/plugin-documentation
  • 其他资源：Strapi Marketplace 页面

安装后，文档插件会检查项目中所有 API 以及配置中指定的任何插件里的内容类型和路由。随后插件会以编程方式生成符合 OpenAPI 规范 的文档。文档插件会生成 paths 对象 和 schema 对象，并将所有 Strapi 类型转换为 OpenAPI 数据类型。

生成的文档 JSON 文件可在你的应用中通过以下路径找到：src/extensions/documentation/documentation/<version>/full_documentation.json

安装

要安装文档插件，请在终端中运行以下命令：

yarn

yarn add @strapi/plugin-documentation

npm

npm install @strapi/plugin-documentation

插件安装完成后，启动 Strapi 即会生成 API 文档。

配置

文档插件的大部分配置选项通过你的 Strapi 项目代码来处理。管理面板中提供少量设置。

管理面板设置

文档插件会影响管理面板的多个部分。下表列出了插件安装后添加到 Strapi 应用中的所有额外选项和设置：

在主导航中新增一个文档选项 ，该选项会显示一个面板，面板上有按钮可打开并重新生成文档。 | | 设置 |

• 新增一个"文档插件"设置分区，用于控制文档端点是否为私有（参见限制访问）。 👉 路径提示： 设置 > 文档插件

• 为访问、更新、删除和重新生成文档启用了基于角色的访问控制。管理员可以在插件标签页和设置标签页中，为不同类型的用户授权不同的访问级别（参见用户与权限文档）。 👉 路径提示： 设置 > 管理面板 > 角色 |

限制对 API 文档的访问 {#restrict-access}

默认情况下，你的 API 文档任何人都可以访问。

要限制 API 文档的访问，请在管理面板中启用 受限访问（Restricted Access）选项：

1. 在管理面板的主导航中进入 设置。
2. 选择 文档。
3. 将 受限访问 开关切换为 ON。
4. 在 password 输入框中定义一个密码。
5. 保存设置。

基于代码的配置

要配置文档插件，请在 src/extensions/documentation/config 文件夹中创建一个 settings.json 文件。在该文件中，你可以指定所有的环境变量、许可证、外部文档链接，以及 规范 中列出的所有条目。

以下是一份示例配置：

{
  "openapi": "3.0.0",
  "info": {
    "version": "1.0.0",
    "title": "DOCUMENTATION",
    "description": "",
    "termsOfService": "YOUR_TERMS_OF_SERVICE_URL",
    "contact": {
      "name": "TEAM",
      "email": "contact-email@something.io",
      "url": "mywebsite.io"
    },
    "license": {
      "name": "Apache 2.0",
      "url": "https://www.apache.org/licenses/LICENSE-2.0.html"
    }
  },
  "x-strapi-config": {
    "plugins": ["upload", "users-permissions"],
    "path": "/documentation"
  },
  "servers": [
    {
      "url": "http://localhost:1337/api",
      "description": "Development server"
    }
  ],
  "externalDocs": {
    "description": "Find out more",
    "url": "https://docs.strapi.io/developer-docs/latest/getting-started/introduction.html"
  },
  "security": [
    {
      "bearerAuth": []
    }
  ]
}

创建文档的新版本 {#create-a-new-version-of-the-documentation}

要创建新版本，请更改 settings.json 文件中的 info.version 键：

{
  "info": {
    "version": "2.0.0"
  }
}

这将自动创建一个新版本。

指定需要生成文档的插件 {#define-which-plugins}

如果你希望插件被纳入文档生成，应将它们加入 x-strapi-config 对象的 plugins 数组中。默认情况下，该数组初始化为 ["upload", "users-permissions"]：

{
  "x-strapi-config": {
    "plugins": ["upload", "users-permissions"]
  }
}

要添加更多插件（例如你的自定义插件），请将它们的名称加入该数组。

如果你不希望插件被纳入文档生成，请提供一个空数组（即 plugins: []）。

覆盖生成的文档

文档插件提供了 3 种覆盖所生成文档的方法：excludeFromGeneration、registerOverride 和 mutateDocumentation。

excludeFromGeneration() {#excluding-from-generation}

要将某些 API 或插件排除在生成范围之外，请使用文档插件 override 服务上的 excludeFromGeneration，该服务位于你的应用或插件的 register 生命周期 中。

module.exports = {
  register({ strapi }) {
    strapi
      .plugin("documentation")
      .service("override")
      .excludeFromGeneration("restaurant");
    // 或多个
    strapi
      .plugin("documentation")
      .service("override")
      .excludeFromGeneration(["address", "upload"]);
  }
}

registerOverride() {#register-override}

如果文档插件未能生成你期望的内容，可以替换已生成的部分。

文档插件暴露了一个 API，允许你替换针对以下 OpenAPI 根级键生成的内容：paths、tags、components 。

要提供覆盖，请使用文档插件 override 服务上的 registerOverride 函数，该服务位于你的应用或插件的 register 生命周期 中。

文档插件会使用注册的覆盖，将生成文档中公共键的值替换为覆盖所提供的值。如果找不到公共键，插件会向生成的文档中添加新的键。

如果覆盖完全替换了文档生成的内容，你可以通过在 options 键数组 excludeFromGeneration 中提供要排除的 API 或插件名称，来指明不再需要生成。

如果覆盖只应应用于特定版本，覆盖必须包含 info.version 的值。否则，该覆盖会作用于所有文档版本。

module.exports = {
  register({ strapi }) {
    if (strapi.plugin('documentation')) {
      const override = {
        // 仅对该覆盖作用于 1.0.0 版本
        info: { version: '1.0.0' },
        paths: {
          '/answer-to-everything': {
            get: {
              responses: { 200: { description: "*" }}
            }
          }
        }
      }

      strapi
        .plugin('documentation')
        .service('override')
        .registerOverride(override, {
          // 指定来源，以防用户不希望记录此插件
          pluginOrigin: 'upload',
          // 覆盖已提供全部内容，无需再生成任何内容
          excludeFromGeneration: ['upload'],
        });
    }
  },
}

覆盖系统是为了尽量简化对所生成文档的修订而提供的。这是插件添加或修改所生成文档的唯一方式。

mutateDocumentation() {#mutate-documentation}

文档插件的配置还接受 info['x-strapi-config'] 上的 mutateDocumentation 函数。该函数接收一个可变的生成文档草稿状态。它只能从应用层应用，并对 OpenAPI schema 拥有最终决定权。

module.exports = {
  documentation: {
    config: {
      "x-strapi-config": {
        mutateDocumentation: (generatedDocumentationDraft) => {
          generatedDocumentationDraft.paths[
            "/answer-to-everything" // 必须是已存在的路径
          ].get.responses["200"].description = "*";
        },
      },
    },
  },
};

使用

文档插件使用 Swagger UI 来可视化你的 API。要访问该 UI，请在管理面板的主导航中选择 。然后点击 打开文档（Open documentation）以打开 Swagger UI。通过 Swagger UI，你可以查看 API 上所有可用的端点并触发 API 调用。

重新生成文档 {#regenerate-documentation}

在对 API 进行更改后，有 2 种方式更新文档：

• 重启你的应用，以重新生成文档插件配置中所指定的文档版本，
• 或进入文档插件页面，点击你想要重新生成的文档版本对应的 重新生成（regenerate）按钮。

对请求进行身份验证

Strapi 默认是安全的，这意味着你的大部分端点都要求用户已通过授权。如果在用户与权限功能中没有将 CRUD 操作设为公开（Public），那么你必须提供你的 JSON Web Token（JWT）。为此，在查看 API 文档时，点击 授权（Authorize）按钮，并将你的 JWT 粘贴到 bearerAuth 的 value 字段中。