文档 Documentation

通过使用 Swagger UI，API 文档插件可以减轻您生成文档的大部分麻烦。

文档插件

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

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

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

安装

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

bash
yarn
bash
yarn strapi install documentation

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

Swagger UI

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

安装后，可以通过以下 URL 访问文档插件 UI： <server-url>:<server-port>/documentation/<documentation-version> （例如，localhost:1337/documentation/v1.0.0)。

经过身份验证的请求

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

管理面板

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

限制对您的 API 文档的访问

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

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

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

重新生成文档

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

  • 重新启动应用程序以重新生成文档插件配置中指定的文档版本，
  • 或转到文档插件页面并单击要重新生成的文档版本的 重新生成 按钮。

配置

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

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

创建文档的新版本

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

config/plugins.js
js
module.exports = {
  documentation: {
    enabled: true,
    config: {
      info: { version: '2.0.0' },
    },
  },
}

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

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

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

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

覆盖生成的文档

从生成中排除

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

excludeFromGeneration 可以更精细地控制生成的内容。

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

excludeFromGeneration()

参数类型说明
api字符串或字符串数组要排除的 API/插件的名称或名称列表
应用程序或插件注册生命周期
js
module.exports = {
  register({ strapi }) {
    strapi
      .plugin('documentation')
      .service('override')
      .excludeFromGeneration('restaurant')
    // or several
    strapi
      .plugin('documentation')
      .service('override')
      .excludeFromGeneration(['address', 'upload'])
  }
}

提供替换文档

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

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

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

registerOverride()

参数类型说明
overrideObjectOpenAPI 对象，包括以下任何键路径、标签、组件。接受 JavaScript、JSON 或 yaml
optionsObject接受 pluginOrigin 和 excludeFromGeneration
options.pluginOrigin字符串正在注册覆盖的插件
options.excludeFromGeneration字符串或字符串数组要排除的 API/插件的名称或名称列表

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

文档插件将使用已注册的覆盖，用覆盖提供的值替换生成的文档上的通用键值。如果未找到通用键，插件将向生成的文档添加新键。

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

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

应用程序或插件注册生命周期
js
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'],
        })
    }
  },
}

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

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

mutateDocumentation()

参数类型描述
generatedDocumentationDraft对象应用覆盖的生成文档作为可变对象
config/plugins.js
js
module.exports = {
  documentation: {
    config: {
      'x-strapi-config': {
        mutateDocumentation: (generatedDocumentationDraft) => {
          generatedDocumentationDraft.paths[
            '/answer-to-everything' // 必须是现有路径
          ].get.responses['200'].description = '*'
        },
      },
    },
  },
}