# OpenAPI 规范
> Source: https://strapi.nodejs.cn/cms/api/openapi
🌐 OpenAPI specification generation
Strapi 提供了一个 CLI 工具，用于自动生成 OpenAPI 3.1.0 规范，记录所有 API 端点、参数和响应。生成的规范可以与 Swagger UI 集成，用于交互式 API 文档。
🌐 Strapi provides a CLI tool to automatically generate OpenAPI 3.1.0 specifications documenting all API endpoints, parameters, and responses. The generated specification can be integrated with Swagger UI for interactive API documentation.
Strapi 提供了一个命令行工具来为你的应用生成 [OpenAPI](https://www.openapis.org/) 规范。
CLI 工具会自动创建全面的 API 文档，描述你 Strapi 应用的内容 API 中所有可用的端点、参数和响应格式。在可能的使用场景中，生成的规范可以集成到像 [Swagger UI ](https://swagger.io/tools/swagger-ui/) 这样的文档工具中。
:::callout 🚧 Experimental feature
OpenAPI 生成特性目前处于实验阶段。其行为和输出在未来版本中可能会发生变化，且不遵循语义化版本控制。如需更多信息和背景，请参阅 [Strapi Contributor Docs ](https://contributor.strapi.io/openapi)。
:::
## 生成 OpenAPI 规范 {#generating-an-openapi-specification}
🌐 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.
:::note Known limitation for nested component `required` metadata
管理面板可以将组件中的内部字段标记为必填，但生成的 OpenAPI 文件仍可能跳过这些标量的 `required` 条目。父对象（例如动态区域内的组件）可能列出 `required`，而嵌套属性则没有。在 [GitHub issue #2236](https://github.com/strapi/documentation/issues/2236) 中有更多背景信息。因此，仅信任原始模式的客户端生成器可能会生成看起来比 Strapi 实际执行更宽松的类型。
🌐 The Admin panel can mark inner fields on a component as required, yet the generated OpenAPI file may still skip a `required` entry for those scalars. The parent object (for instance a component inside a dynamic zone) might list `required` while the nested properties do not. There is more background in [GitHub issue #2236](https://github.com/strapi/documentation/issues/2236). Client generators that trust the raw schema alone can therefore emit types that look looser than what Strapi actually enforces.
此区域仍处于实验阶段，与页面顶部的警告横幅相同，因此请继续在应用代码中或使用控制器指南中的 [REST 验证助手](/cms/backend-customization/controllers#sanitization-and-validation-in-controllers) 验证嵌套负载，而不要假设每条管理员规则都已反映在导出的 JSON 模式中。
🌐 This area is still experimental, same as the warning banner at the top of the page, so keep validating nested payloads in application code or with the [REST validation helpers](/cms/backend-customization/controllers#sanitization-and-validation-in-controllers) from the controllers guide instead of assuming every Admin rule is mirrored in the exported JSON schema yet.
:::
### 命令行接口使用 {#cli-usage}
🌐 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:
```shell
yarn strapi openapi generate
```
```shell
npm run strapi openapi generate
```
你还可以传递一个可选的 `--output` 参数来指定路径和文件名，如下面的示例所示：
🌐 You can also pass an optional `--output` argument to specify the path and filename, as in the following example:
```bash
yarn strapi openapi generate --output ./docs/api-spec.json
```
```bash
npm run strapi openapi generate -- --output ./docs/api-spec.json
```
### 规范结构和内容 {#specification-structure-and-content}
🌐 Specification structure and content
生成的 OpenAPI 规范遵循 [OpenAPI 3.1.0 standard](https://spec.openapis.org/oas/v3.1.0.html) ，并可能在以下简化示例中显示如下：
```json
{
"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": "string" },
"title": { "type": "string" },
"content": { "type": "string" }
}
}
}
}
}
```