生成 OpenAPI 规范

生成的 OpenAPI 规范包含你的 Strapi 应用中所有可用的 API 端点，以及关于这些端点的信息，例如：

• 所有内容类型的 CRUD 操作
• 你的应用中定义的自定义 API 路由
• 用于用户管理的身份验证端点
• 用于媒体处理的文件上传端点
• 已安装插件提供的插件端点

配置

默认情况下，Strapi 不会为生成的 OpenAPI 规范暴露 HTTP 端点。要启用此功能，请在 /config/server 文件中添加 openapi 键。

HTTP 端点访问

openapi 配置接受 2 个子键：content-api 和 admin，每个都带有一个 access 属性：

以下示例同时暴露这两个端点：

JavaScript

module.exports = {
  openapi: {
    'content-api': {
      access: 'public',
    },
    admin: {
      access: 'authenticated',
    },
  },
};

TypeScript

export default {
  openapi: {
    'content-api': {
      access: 'public',
    },
    admin: {
      access: 'authenticated',
    },
  },
};

端点选项

除了 access 之外，每个端点（content-api 和 admin）还接受以下选项：

使用默认的 route.path 时，Content API 端点的完整 URL 为 http://localhost:1337/api/openapi.json，Admin 端点为 http://localhost:1337/admin/openapi.json。

与 Swagger UI 集成

通过以下步骤，你可以快速生成一个兼容 Swagger UI 的页面：

1. 生成规范：

   Yarn

   yarn strapi openapi generate --output ./public/swagger-spec.json
   

   NPM

   npm run strapi openapi generate -- --output ./public/swagger-spec.json
   

2. 使用以下代码更新 the /config/middlewares.js 配置文件：

   JavaScript

   module.exports = [
     'strapi::logger',
     'strapi::errors',
     {
       name: 'strapi::security',
       config: {
         contentSecurityPolicy: {
           useDefaults: true,
           directives: {
             'script-src': ["'self'", "'unsafe-inline'", 'https://unpkg.com'],
             'style-src': ["'self'", "'unsafe-inline'", 'https://unpkg.com'],
             'connect-src': ["'self'", 'https:'],
             'img-src': ["'self'", 'data:', 'blob:', 'https:'],
             'media-src': ["'self'", 'data:', 'blob:'],
             upgradeInsecureRequests: null,
           },
         },
       },
     },
     'strapi::cors',
     'strapi::poweredBy',
     'strapi::query',
     'strapi::body',
     'strapi::session',
     'strapi::favicon',
     'strapi::public',
   ];
   

   TypeScript

   export default [
     'strapi::logger',
     'strapi::errors',
     {
       name: 'strapi::security',
       config: {
         contentSecurityPolicy: {
           useDefaults: true,
           directives: {
             'script-src': ["'self'", "'unsafe-inline'", 'https://unpkg.com'],
             'style-src': ["'self'", "'unsafe-inline'", 'https://unpkg.com'],
             'connect-src': ["'self'", 'https:'],
             'img-src': ["'self'", 'data:', 'blob:', 'https:'],
             'media-src': ["'self'", 'data:', 'blob:'],
             upgradeInsecureRequests: null,
           },
         },
       },
     },
     'strapi::cors',
     'strapi::poweredBy',
     'strapi::query',
     'strapi::body',
     'strapi::session',
     'strapi::favicon',
     'strapi::public',
   ];
   

   这将确保来自 unpkg.com 的 Swagger UI 显示不会被 安全中间件 处理的 Strapi CSP 策略所阻止。

3. 在你的 Strapi 项目中创建一个 public/openapi.html 文件以显示 Swagger UI，代码如下：

   <!DOCTYPE html>
   <html>
     <head>
       <title>API Documentation</title>
       <link
         rel="stylesheet"
         type="text/css"
         href="https://unpkg.com/swagger-ui-dist@5.0.0/swagger-ui.css"
       />
     </head>
     <body>
       <div id="swagger-ui"></div>
       <script src="https://unpkg.com/swagger-ui-dist@5.0.0/swagger-ui-bundle.js"></script>
       <script src="https://unpkg.com/swagger-ui-dist@5.0.0/swagger-ui-standalone-preset.js"></script>
       <script>
         window.onload = function () {
           SwaggerUIBundle({
             url: './swagger-spec.json',
             dom_id: '#swagger-ui',
             presets: [
               SwaggerUIBundle.presets.apis,
               SwaggerUIStandalonePreset
             ],
             layout: 'StandaloneLayout',
           });
         };
       </script>
     </body>
   </html>
   

4. 使用 yarn develop 或 npm run develop 重启 Strapi 服务器，并访问 /openapi.html 页面。Swagger UI 应当会被显示：