OpenAPI 规范生成

¥OpenAPI specification generation

Strapi 提供了一个命令行工具，用于为你的应用生成 OpenAPI 规范。

¥Strapi provides a command-line tool to generate OpenAPI specifications for your applications.

CLI 工具会自动创建全面的 API 文档，描述 Strapi 应用的 Content API 中所有可用的端点、参数和响应格式。在可能的用例中，生成的规范可以轻松集成到文档工具中，例如招摇的用户界面。

¥The CLI tool automatically creates comprehensive API documentation that describes all available endpoints, parameters, and response formats in your Strapi application's Content API. Among the possible use cases, the generated specification can then be easily integrated into documentation tools like Swagger UI .

🚧 实验特性

OpenAPI 生成功能目前处于实验阶段。其行为和输出可能会在未来版本中发生变化，而不会遵循语义版本控制。有关更多信息和上下文，请参阅 Strapi 贡献者文档。

¥The OpenAPI generation feature is currently experimental. Its behavior and output might change in future releases without following semantic versioning. For additional information and context, please refer to the Strapi Contributor Docs .

生成 OpenAPI 规范

¥Generating an OpenAPI specification

OpenAPI 生成工具包含在 Strapi 核心中，无需额外安装。你可以在任何 Strapi 项目中直接从命令行使用它来生成全面的 API 文档。

¥The OpenAPI generation tool is included with Strapi core and doesn't require additional installation. You can use it directly from the command line in any Strapi project to generate comprehensive API documentation.

CLI 使用

¥CLI usage

不带任何参数执行该命令将在你的 Strapi 文件夹项目根目录下生成一个 specification.json 文件：

¥Executing the command without any arguments will generate a specification.json file at the root of your Strapi folder project:

Yarn
NPM

yarn strapi openapi generate

npm run strapi openapi generate

你还可以使用可选的 --output 参数来指定路径和文件名，如下例所示：

¥You can also path an optional --output argument to specify the path and filename, as in the following example:

Yarn
NPM

yarn strapi openapi generate --output ./docs/api-spec.json

npm run strapi openapi generate -- --output ./docs/api-spec.json

规范结构和内容

¥Specification structure and content

生成的 OpenAPI 规范遵循 OpenAPI 3.1.0 标准，可能类似于以下简化示例：

¥The generated OpenAPI specification follows the OpenAPI 3.1.0 standard and could look like in the following shortened example:

{
  "openapi": "3.1.0",
  "x-powered-by": "strapi",
  "x-strapi-version": "5.21.0",
  "info": {
    "title": "My Strapi API",
    "description": "API documentation for My Strapi API",
    "version": "1.0.0"
  },
  "paths": {
    "/api/articles": {
      "get": {
        "operationId": "article/get/articles",
        "parameters": [
          {
            "name": "fields",
            "in": "query",
            "schema": {
              "type": "array",
              "items": { "type": "string" }
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": { "$ref": "#/components/schemas/Article" }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Article": {
        "type": "object",
        "properties": {
          "id": { "type": "integer" },
          "title": { "type": "string" },
          "content": { "type": "string" }
        }
      }
    }
  }
}

Download an example of a complete specification file

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

¥The generated OpenAPI specification includes all available API endpoints in your Strapi application, and information about these endpoints, such as the following:

适用于所有内容类型的 CRUD 操作

¥CRUD operations for all content types
应用中定义的自定义 API 路由

¥Custom API routes defined in your application
用于用户管理的身份验证端点

¥Authentication endpoints for user management
用于媒体处理的文件上传端点

¥File upload endpoints for media handling
已安装插件的插件端点

¥Plugin endpoints from installed plugins

与 Swagger UI 集成

¥Integrating with Swagger UI

通过以下步骤，你可以快速生成与招摇的用户界面兼容的页面：

¥With the following steps you can quickly generate a Swagger UI-compatible page:

生成规范：

¥Generate a specification:

Yarn
NPM

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

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

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

¥Update the /config/middlewares.js configuration file with the following code:

JavaScript
TypeScript

```js title="/config/middlewares.js"
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',
];
```

```js title="/config/middlewares.ts"
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',
];
```

This will ensure the Swagger UI display from <ExternalLink to="https://unpkg.com/" text="unpkg.com" /> is not blocked by Strapi's CSP policy handled by the [security middleware](/cms/configurations/middlewares#security).

```html
<!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.Swagger UI 应显示如下：

¥4. Restart the Strapi server with yarn develop or npm run develop and visit the /openapi.html page. The Swagger UI should be displayed:

Swagger UI example with Strapi OpenAPI specification

生成 OpenAPI 规范​

CLI 使用​

规范结构和内容​

与 Swagger UI 集成​

生成 OpenAPI 规范

CLI 使用

规范结构和内容

与 Swagger UI 集成