文档插件

¥Documentation plugin

创建 API 后，文档插件可用于记录可用端点。

¥The Documentation plugin is useful to document the available endpoints once you created an API.

如果安装，文档插件将检查项目中所有 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.

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

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

安装

¥Installation

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

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

yarn
npm

yarn add @strapi/plugin-documentation

npm install @strapi/plugin-documentation

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

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

招摇的用户界面

¥Swagger UI

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

¥The Documentation plugin visualizes your API using Swagger UI. To access the UI, select Plugins > Documentation 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 访问文档插件 UI：<server-url>:<server-port>/documentation/<documentation-version>（例如，localhost:1337/documentation/v1.0.0）。

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

经过身份验证的请求

¥Authenticated requests

Strapi 默认情况下是安全的，这意味着你的大多数端点都需要用户获得授权。如果该操作尚未在用户和权限中设置为公开，则你必须提供你的 JWT。为此，请单击“授权”按钮并粘贴你的 JWT。

¥Strapi is secured by default, which means that most of your end-points require the user to be authorized. If the action has not been set to public in users and permission then you must provide your JWT. To do this, click the “Authorize” button and paste your JWT.

管理面板

¥Administration panel

该插件附带一个可在管理面板中使用的界面和一个配置文件。

¥This plugin comes with an interface that is available in your administration panel and a configuration file.

限制对 API 文档的访问

¥Restrict the access to your API documentation

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

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

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

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

导航
¥Navigate to

管理面板主导航中的设置。2.3.4.5.

¥Settings in the main navigation of the admin panel. 2. Choose Documentation. 3. Toggle Restricted Access to ON. 4. Define a password in the password input. 5. Save the settings.

重新生成文档

¥Regenerate 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.

配置

¥Configuration

文档插件使用以下配置进行初始化，其中所有属性都可以通过向 config/plugins.js 中文档插件的配置对象提供新值来更改：

¥The Documentation plugin is initialized with the following configuration, where all properties can be altered by providing new values to the documentation plugin's configuration object in config/plugins.js:

module.exports = {
  documentation: {
    enabled: true,
    config: {
      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': {
        // Leave empty to ignore plugins during generation
        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: [] } ]
    }
  }
}

创建新版本的文档

¥Create a new version of the documentation

要创建文档的新版本，请按如下方式更新 version 密钥：

¥To create a new version of your documentation, update the version key as follows:

config/plugins.js

module.exports = {
  documentation: {
    enabled: true,
    config: {
      info: { version: "2.0.0" },
    },
  },
};

指示哪些插件需要生成文档

¥Indicate 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 on the x-strapi-config. By default, the array is initialized with ["upload", "users-permissions"].

同样，如果你不希望插件包含在文档生成中，请提供一个空数组：

¥Similarly, if you do not want plugins to be included in documentation generation, provide an empty array:

config/plugins.js

module.exports = {
  documentation: {
    enabled: true,
    config: {
      "x-strapi-config": {
        // Default
        plugins: ["upload", "users-permissions"],
        // Custom
        plugins: ["upload"],
        // Do not generate for plugins
        plugins: [],
      },
    },
  },
};

覆盖生成的文档

¥Overriding the generated documentation

从世代中排除

¥Excluding from generation

要排除生成某些 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.

excludeFromGeneration()

范围	类型	描述
`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"]);
  }
}

提供更换文件

¥Providing replacement documentation

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

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

registerOverride()

范围	类型	描述
`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.

文档插件的配置还接受 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.

mutateDocumentation()

范围	类型	描述
`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 = "*";
        },
      },
    },
  },
};

文档插件

安装​

招摇的用户界面​

经过身份验证的请求​

管理面板​

限制对 API 文档的访问​

重新生成文档​

配置​

创建新版本的文档​

指示哪些插件需要生成文档​

覆盖生成的文档​

从世代中排除​

提供更换文件​

安装