Skip to main content

文档插件

🌐 Documentation plugin

Page summary:

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

文档插件可以自动化生成你的 API 文档。它基本上会生成一个 Swagger 文件。它遵循 Open API specification version。

IDENTITY CARD
位置

可以通过管理面板使用。
可以通过管理面板和服务器代码进行配置，具有不同的选项集。

包名

@strapi/plugin-documentation

附加资源
Strapi Marketplace page
Unmaintained plugin

文档插件未主动维护，可能无法与 Strapi 5 兼容。

🌐 The Documentation plugin is not actively maintained and may not work with Strapi 5.

如果已安装，Documentation 插件将检查项目中所有 API 以及配置中指定的任何插件所发现的内容类型和路由。然后，该插件将以编程方式生成与 OpenAPI specification匹配的文档。Documentation 插件生成 paths objects 和 schema objects ，并将所有 Strapi 类型转换为 OpenAPI data types。

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

安装​

🌐 Installation

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

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

terminal
yarn add @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:

受影响的部分选项和设置
文档
    在主导航中添加了一个新的文档选项 ，该选项显示一个带有按钮的面板，用于 打开和 重新生成文档。
设置
  • 新增“文档插件”设置部分，用于控制文档端点是否为私有（参见访问限制）。
    👉 路径提示： 设置 > 文档插件

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

限制访问你的 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. 在管理员面板的主导航中，导航到 设置。
  2. 选择 文档。
  3. 切换 受限访问 到 ON。
  4. 在 password 输入框中定义一个密码。
  5. 保存设置。

基于代码的配置​

🌐 Code-based configuration

要配置文档插件，请在 src/extensions/documentation/config 文件夹中创建一个 settings.json 文件。在此文件中，你可以指定所有环境变量、许可证、外部文档链接，以及 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": []
    }
  ]
}
Tip

如果你需要添加自定义键，请在其前加上 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()​

🌐 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.

Note

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

例如，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.

Documentation 插件提供了一个 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 对象，包括以下任意键：paths、tags、components。接受 JavaScript、JSON 或 YAML
options对象接受 pluginOrigin 和 excludeFromGeneration
options.pluginOrigin字符串注册覆盖的插件
options.excludeFromGeneration字符串 或 字符串数组要排除的 API/插件的名称，或名称列表
Caution

提供覆盖的插件开发者应始终指定 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

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

Tip

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

重新生成文档​

🌐 Regenerating documentation

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

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

  • 重新启动你的应用以重新生成文档插件配置中指定的文档版本，
  • 或者转到文档插件页面，然后点击你想要重新生成的文档版本的重新生成按钮。

认证请求​

🌐 Authenticating requests

Strapi 默认是安全的，这意味着大多数端点都需要用户被授权。如果在 用户与权限功能 中 CRUD 操作未设置为公开，那么你必须提供你的 JSON Web 令牌（JWT）。为此，在查看 API 文档时，点击 授权 按钮，并将你的 JWT 粘贴到 bearerAuth value 字段中。

🌐 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.

On this page