文档插件

¥Documentation plugin

文档插件可自动创建你的 API 文档。它基本上会生成一个 swagger 文件。它遵循 开放 API 规范版本 。

¥The Documentation plugin automates your API documentation creation. It basically generates a swagger file. It follows the Open API specification version .

插件的身份证

位置:可通过管理面板使用。通过管理面板和服务器代码进行配置，具有不同的选项集。
包名称：@strapi/plugin-documentation
其他资源：Strapi 市场页面 

¥ Location: Usable via the admin panel. Configured through both admin panel and server code, with different sets of options.
Package name: @strapi/plugin-documentation
Additional resources: Strapi Marketplace page 

如果安装，文档插件将检查项目中所有 API 以及配置中指定的任何插件上找到的内容类型和路由。然后，插件将以编程方式生成文档以匹配 开放 API 规范 。文档插件生成 路径对象  和 模式对象  并将所有 Strapi 类型转换为 OpenAPI 数据类型 。

¥If installed, the Documentation plugin will inspect content types and routes found on all APIs in your project and any plugin specified in the configuration. The plugin will then programmatically generate documentation to match the OpenAPI specification . The Documentation plugin generates the paths objects  and schema objects  and converts all Strapi types to OpenAPI data types .

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

¥The generated documentation JSON file can be found in your application at the following path: src/extensions/documentation/documentation/<version>/full_documentation.json

安装

¥Installation

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

¥To install the documentation plugin, run following command in your terminal:

yarn

yarn add @strapi/plugin-documentation

npm

npm install @strapi/plugin-documentation

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

¥Once the plugin is installed, starting Strapi generates the API documentation.

配置

¥Configuration

文档插件的大多数配置选项都通过你的 Strapi 项目的代码处理。管理面板中提供了一些设置。

¥Most configuration options for the Documentation plugin are handled via your Strapi project's code. A few settings are available in the admin panel.

管理面板设置

¥Admin panel settings

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

¥The Documentation plugin affects multiple parts of the admin panel. The following table lists all the additional options and settings that are added to a Strapi application once the plugin has been installed:

Section impacted	Options and settings
Documentation	Addition of a new Documentation option in the main navigation which shows a panel with buttons to open and regenerate the documentation.
Settings	Addition of a "Documentation plugin" setting section, which controls whether the documentation endpoint is private or not (see restricting access). 👉 Path reminder: Settings > Documentation plugin Activation of role based access control for accessing, updating, deleting, and regenerating the documentation. Administrators can authorize different access levels to different types of users in the Plugins tab and the Settings tab (see Users & Permissions documentation). 👉 Path reminder: Settings > Administration Panel > Roles

限制对你的 API 文档的访问

¥Restricting access to your API documentation

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

¥By default, your API documentation will be accessible by anyone.

要限制 API 文档访问，请从管理面板启用“受限访问”选项：

¥To restrict API documentation access, enable the Restricted Access option from the admin panel:

1. 在管理面板的主导航中导航到 设置。

   ¥Navigate to Settings in the main navigation of the admin panel.

2. 选择文档。

   ¥Choose Documentation.

3. 切换对 ON 的受限访问。

   ¥Toggle Restricted Access to ON.

4. 在 password 输入中定义密码。

   ¥Define a password in the password input.

5. 保存设置。

   ¥Save the settings.

基于代码的配置

¥Code-based configuration

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

¥To configure the Documentation plugin, create a settings.json file in the src/extensions/documentation/config folder. In this file, you can specify all your environment variables, licenses, external documentation links, and all the entries listed in the specification .

以下是配置示例：

¥The following is an example configuration:

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://strapi.nodejs.cn/developer-docs/latest/getting-started/introduction.html"
  },
  "security": [
    {
      "bearerAuth": []
    }
  ]
}

提示

如果你需要添加自定义密钥，请在其前面加上 x-（例如 x-strapi-something）。

¥If you need to add a custom key, prefix it by x- (e.g., x-strapi-something).

创建新版本的文档

¥Creating a new version of the documentation

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

¥To create a new version, change the info.version key in the settings.json file:

src/extensions/documentation/config/settings.json

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

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

¥This will automatically create a new version.

定义哪些插件需要生成文档

¥Defining which plugins need documentation generated

如果你希望插件包含在文档生成中，则应将它们包含在 x-strapi-config 对象中的 plugins 数组中。默认情况下，数组使用 ["upload", "users-permissions"] 初始化：

¥If you want plugins to be included in documentation generation, they should be included in the plugins array in the x-strapi-config object. By default, the array is initialized with ["upload", "users-permissions"]:

src/extensions/documentation/config/settings.json

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

要添加更多插件（例如你的自定义插件），请将其名称添加到数组中。

¥To add more plugins, such as your custom plugins, add their name to the array.

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

¥If you do not want plugins to be included in documentation generation, provide an empty array (i.e., plugins: []).

覆盖生成的文档

¥Overriding the generated documentation

文档插件有 3 种方法来覆盖生成的文档：excludeFromGeneration、registerOverride 和 mutateDocumentation。

¥The Documentation plugins comes with 3 methods to override the generated documentation: excludeFromGeneration, registerOverride, and mutateDocumentation.

excludeFromGeneration()

要排除生成某些 API 或插件，请使用在应用或插件的 register 生命周期 中的文档插件的 override 服务中找到的 excludeFromGeneration。

¥To exclude certain APIs or plugins from being generated, use the excludeFromGeneration found on the documentation plugin’s override service in your application or plugin's register lifecycle.

注意

excludeFromGeneration 对生成的内容提供了更细粒度的控制。

¥excludeFromGeneration gives more fine-grained control over what is generated.

例如，pluginA 可能会创建几个新的 API，而 pluginB 可能只想为其中一些 API 生成文档。在这种情况下，pluginB 仍然可以通过仅排除不需要的内容来从它确实需要的生成文档中受益。

¥For example, pluginA might create several new APIs while pluginB may only want to generate documentation for some of those APIs. In that case, pluginB could still benefit from the generated documentation it does need by excluding only what it does not need.

---

范围	类型	描述
api	字符串或字符串数组	要排除的 API/插件的名称或名称列表

Application or plugin register lifecycle

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

registerOverride()

如果文档插件无法生成你期望的内容，则可以替换已生成的内容。

¥If the Documentation plugin fails to generate what you expect, it is possible to replace what has been generated.

文档插件公开了一个 API，允许你替换为以下 OpenAPI 根级别密钥生成的内容：paths、tags、components。

¥The Documentation plugin exposes an API that allows you to replace what was generated for the following OpenAPI root level keys: paths, tags, components .

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

¥To provide an override, use the registerOverride function found on the Documentation plugin’s override service in your application or plugin's register lifecycle.

范围	类型	描述
override	目的	OpenAPI 对象包括以下任意键路径、标签、组件。接受 JavaScript、JSON 或 yaml
options	目的	接受 pluginOrigin 和 excludeFromGeneration
options.pluginOrigin	字符串	正在注册覆盖的插件
options.excludeFromGeneration	字符串或字符串数组	要排除的 API/插件的名称或名称列表

提醒

提供覆盖的插件开发者应始终指定 pluginOrigin 选项键。否则，无论用户的配置如何，覆盖都会运行。

¥Plugin developers providing an override should always specify the pluginOrigin options key. Otherwise the override will run regardless of the user’s configuration.

文档插件将使用注册的覆盖将生成的文档上的公共键值替换为覆盖提供的值。如果没有找到通用密钥，插件会将新密钥添加到生成的文档中。

¥The Documentation plugin will use the registered overrides to replace the value of common keys on the generated documentation with what the override provides. If no common keys are found, the plugin will add new keys to the generated documentation.

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

¥If the override completely replaces what the documentation generates, you can specify that generation is no longer necessary by providing the names of the APIs or plugins to exclude in the options key array excludeFromGeneration.

如果覆盖仅应用于特定版本，则覆盖必须包含 info.version 的值。否则，覆盖将在所有文档版本上运行。

¥If the override should only be applied to a specific version, the override must include a value for info.version. Otherwise, the override will run on all documentation versions.

Application or plugin register lifecycle

module.exports = {
  register({ strapi }) {
    if (strapi.plugin('documentation')) {
      const override = {
        // Only run this override for version 1.0.0
        info: { version: '1.0.0' },
        paths: {
          '/answer-to-everything': {
            get: {
              responses: { 200: { description: "*" }}
            }
          }
        }
      }

      strapi
        .plugin('documentation')
        .service('override')
        .registerOverride(override, {
          // Specify the origin in case the user does not want this plugin documented
          pluginOrigin: 'upload',
          // The override provides everything don't generate anything
          excludeFromGeneration: ['upload'],
        });
    }
  },
}

提供覆盖系统是为了尝试并简化对生成的文档的修改。这是插件添加或修改生成的文档的唯一方法。

¥The overrides system is provided to try and simplify amending the generated documentation. It is the only way a plugin can add or modify the generated documentation.

mutateDocumentation()

文档插件的配置还接受 info['x-strapi-config'] 上的 mutateDocumentation 函数。此函数接收生成的文档的草稿状态，该文档可以进行更改。它只能从应用应用，并且在 OpenAPI 架构中拥有最终决定权。

¥The Documentation plugin’s configuration also accepts a mutateDocumentation function on info['x-strapi-config']. This function receives a draft state of the generated documentation that be can be mutated. It should only be applied from an application and has the final say in the OpenAPI schema.

范围	类型	描述
generatedDocumentationDraft	目的	生成的文档应用了作为可变对象的覆盖

config/plugins.js

module.exports = {
  documentation: {
    config: {
      "x-strapi-config": {
        mutateDocumentation: (generatedDocumentationDraft) => {
          generatedDocumentationDraft.paths[
            "/answer-to-everything" // must be an existing path
          ].get.responses["200"].description = "*";
        },
      },
    },
  },
};

用法

¥Usage

文档插件使用 招摇的用户界面  可视化你的 API。要访问 UI，请在管理面板的主导航中选择 。然后单击“打开文档”以打开 Swagger UI。使用 Swagger UI，你可以查看 API 上可用的所有端点并触发 API 调用。

¥The Documentation plugin visualizes your API using Swagger UI . To access the UI, select in the main navigation of the admin panel. Then click Open documentation to open the Swagger UI. Using the Swagger UI you can view all of the endpoints available on your API and trigger API calls.

提示

安装插件后，可以通过以下 URL 访问插件用户界面：<server-url>:<server-port>/documentation/<documentation-version>（例如，`localhost:1337/documentation/v1.0.0` ）。

¥Once the plugin is installed, the plugin user interface can be accessed at the following URL: <server-url>:<server-port>/documentation/<documentation-version> (e.g., `localhost:1337/documentation/v1.0.0` ).

重新生成文档

¥Regenerating documentation

更改 API 后，有 2 种方法可以更新文档：

¥There are 2 ways to update the documentation after making changes to your API:

• 重新启动你的应用以重新生成文档插件配置中指定的文档版本，

  ¥restart your application to regenerate the version of the documentation specified in the Documentation plugin's configuration,

• 或者转到文档插件页面，然后单击你要重新生成的文档版本的重新生成按钮。

  ¥or go to the Documentation plugin page and click the regenerate button for the documentation version you want to regenerate.

验证请求

¥Authenticating requests

Strapi 默认是安全的，这意味着你的大多数端点都需要用户获得授权。如果 用户和权限功能 中的 CRUD 操作未设置为 Public，则必须提供 JSON Web 令牌 (JWT)。为此，在查看 API 文档时，单击授权按钮并将你的 JWT 粘贴到 bearerAuth 值字段中。

¥Strapi is secured by default, which means that most of your endpoints require the user to be authorized. If the CRUD action has not been set to Public in the Users & Permissions feature then you must provide your JSON web token (JWT). To do this, while viewing the API Documentation, click the Authorize button and paste your JWT in the bearerAuth value field.