OpenAPI 设置 - Mintlify

OpenAPI 是用于描述 API 的规范。Mintlify 支持 OpenAPI 3.0 和 3.1 文档，用于生成交互式 API 文档并保持其始终最新。

添加 OpenAPI 规范文件

要使用 OpenAPI 为你的端点撰写文档，你需要一个或多个有效的 OpenAPI 规范文件，格式为 JSON 或 YAML，并且遵循 OpenAPI 3.0 或 3.1 规范。将 OpenAPI 规范添加到你的文档存储库中，或将其托管在线，以便你可以通过 URL 访问这些规范。存储在存储库中的规范会在你的文档域名上按照其路径提供为可下载文件。例如，https://your-domain/docs/openapi.json。在 docs.json 的 navigation 配置中引用任意数量的 OpenAPI 规范，以为你的 API 端点创建页面。每个规范文件都会生成自己的一组端点。

"navigation": {
  "tabs": [
    {
      "tab": "API Reference",
      "openapi": "openapi.json"
    }
  ]
}

Mintlify 仅支持在单个 OpenAPI 文档内使用 $ref 进行内部引用，不支持外部引用。

描述你的 API

我们推荐以下资源，帮助你学习并编写 OpenAPI 规范。

Swagger 的 OpenAPI 指南，用于学习 OpenAPI 语法。
OpenAPI 规范的 Markdown 源文件，用于查阅最新版 OpenAPI 规范的详细信息。
Swagger Editor，用于编辑、验证和调试你的 OpenAPI 文档。
Mint CLI，可通过以下命令验证你的 OpenAPI 文档：mint validate。

Swagger 的 OpenAPI 指南面向 OpenAPI v3.0，但其中几乎所有信息同样适用于 v3.1。关于 v3.0 与 v3.1 的差异，请参阅 OpenAPI 博客中的 Migrating from OpenAPI 3.0 to 3.1.0。

指定 API 的基础 URL

要启用 API playground，请在 OpenAPI 规范中添加 servers 字段，并填写 API 的基础 URL。

{
  "servers": [
    {
      "url": "https://api.example.com/v1"
    }
  ]
}

在 OpenAPI 规范中，不同的 API 端点通过其路径来定义，例如 /users/{id}，或直接使用 /。基础 URL 用于指明这些路径应追加到哪里。有关如何配置 servers 字段的更多信息，请参阅 OpenAPI 文档中的 API Server and Base Path。 API playground 会使用这些服务器 URL 来确定请求的发送目标。如果你指定了多个服务器，将提供一个下拉菜单，允许用户在不同服务器之间切换。如果未指定服务器，API playground 会使用简易模式，因为在没有基础 URL 的情况下无法发送请求。如果你的 API 的端点分布在不同的 URL 下，你可以为特定路径或操作覆盖 servers 字段。

指定身份验证

要在 API 文档与操练场中启用身份验证，请在 OpenAPI 规范中配置 securitySchemes 和 security 字段。API 描述与 API 操练场会根据 OpenAPI 规范中的安全配置自动添加身份验证字段。

定义你的身份验证方式。

添加 securitySchemes 字段来定义用户如何进行身份验证。以下示例展示了 Bearer 身份验证的配置：

{
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}

将身份验证应用到你的端点。

添加 security 字段以要求进行身份验证。

{
  "security": [
    {
      "bearerAuth": []
    }
  ]
}

常见的身份验证类型包括：

API Keys: 适用于基于 header、query 或 cookie 的密钥。
Bearer: 适用于 JWT 或 OAuth 令牌。
Basic: 适用于用户名与密码。

如果你的 API 中不同的端点需要不同的身份验证方式，你可以为某个操作覆盖 security 字段。有关定义和应用身份验证的更多信息，请参阅 OpenAPI 文档中的Authentication。

为安全方案设置默认值

在安全方案上使用 x-default 扩展，可以在 API playground 中预填身份验证字段。这对于提供占位值或测试凭据非常有用，能帮助用户快速上手。

{
  "components": {
    "securitySchemes": {
      "apiKey": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key",
        "x-default": "your-api-key-here"
      }
    }
  }
}

x-default 扩展支持 apiKey 和 http bearer 安全方案类型。该值作为 playground 身份验证字段中的默认输入显示。你还可以在 OpenAPI 规范中的任何 schema 属性上使用 x-default，以在 API playground 中设置默认值，而不影响 schema 定义中的 default 字段。

仅当你在 enum 属性上显式设置 example 或 default 时，API playground 才会预填该字段。如果两者都未设置，Mintlify 不会自动预填 enum 的第一个值，因此在用户选择之前该字段保持为空。

自定义端点页面

在 OpenAPI 规范中添加 x-mint 扩展即可自定义端点页面。x-mint 扩展可让你进一步控制 API 文档的生成与展示方式。

元数据

在任意操作中添加 x-mint: metadata，即可覆盖生成的 API 页面的默认元数据。除了 openapi 之外，你可以使用 MDX frontmatter 中任意有效的元数据字段。

{
  "paths": {
    "/users": {
      "get": {
        "summary": "Get users",
        "description": "Retrieve a list of users",
        "x-mint": {
          "metadata": {
            "title": "List all users",
            "sidebarTitle": "List users",
            "description": "获取分页用户数据及筛选选项",
            "og:title": "Display a list of users"
          }
        },
        "parameters": [
          {
            // Parameter configuration
          }
        ]
      }
    }
  }
}

你还可以使用 playground 和 groups metadata 字段，为每个 endpoint 单独控制 playground 的展示：

{
  "paths": {
    "/admin/users": {
      "post": {
        "summary": "创建管理员用户",
        "x-mint": {
          "metadata": {
            "playground": "auth",
            "groups": ["admin"],
            "public": true
          }
        }
      }
    }
  }
}

此配置会让页面对所有人可见，但只有属于 admin 组的已认证用户才能使用交互式 Playground。

内容

使用 x-mint: content 在自动生成的 API 文档之前添加内容。x-mint: content 扩展支持所有 Mintlify MDX 组件和格式。

{
  "paths": {
    "/users": {
      "post": {
        "summary": "创建用户",
        "x-mint": {
          "content": "## 前提条件\n\n此端点需要管理员权限,并设有速率限制。\n\n<Note>用户邮箱在系统内必须唯一。</Note>"
        },
        "parameters": [
          {
            // 参数配置
          }
        ]
      }
    }
  }
}

href

使用 x-mint: href 设置自动生成的端点页面的 URL。当存在 x-mint: href 时，生成的 API 页面将使用指定的 URL，而不是默认自动生成的 URL。

{
  "paths": {
    "/legacy-endpoint": {
      "get": {
        "summary": "旧版端点",
        "x-mint": {
          "href": "/deprecated-endpoints/legacy-endpoint"
        }
      }
    },
    "/documented-elsewhere": {
      "post": {
        "summary": "特殊端点",
        "x-mint": {
          "href": "/guides/special-endpoint-guide"
        }
      }
    }
  }
}

参数标签

使用任意 schema 上的 x-mint.pre 和 x-mint.post，为 API 参考和 playground 中的参数添加自定义标签。pre 标签会渲染在参数名称之前，post 标签会渲染在参数名称之后，与 Mintlify 内置的 required、read-only 和 write-only 等标签并排显示。这两个字段都接受字符串数组。每个字符串都会成为一个独立的标签。

{
  "components": {
    "schemas": {
      "User": {
        "properties": {
          "email": {
            "type": "string",
            "x-mint": {
              "pre": ["PII"],
              "post": ["indexed", "unique"]
            }
          }
        }
      }
    }
  }
}

若要在所有参数上显示任意 OpenAPI 规范字段作为标签，而无需逐个修改 schema，请在 docs.json 中配置 api.params.post。列出你希望显示的字段键名，Mintlify 会从 schema 中读取每个值，并自动渲染相应的标签。

{
  "api": {
    "params": {
      "post": ["nullable", "x-internal"]
    }
  }
}

通过此配置，类似 { "type": "string", "nullable": true, "x-internal": "admin" } 的属性会在其名称旁渲染 nullable 和 admin 标签。post 标签按以下顺序显示：内置标签（read-only、write-only）、由 api.params.post 配置驱动的标签，然后是逐属性配置的 x-mint.post 标签。

分组显示名称

使用 tag 对象上的 x-group 扩展为某个 tag 的导航分组设置自定义显示名称。默认情况下，Mintlify 将 tag 的 name 同时用作导航分组标签和 URL 路径段。x-group 扩展会覆盖分组标签，同时保留 tag 名称用于 URL。当你希望使用一个易于阅读的分组名称，而该名称与 API 路径中使用的 tag 不同时，这非常有用。

{
  "tags": [
    {
      "name": "user-management",
      "description": "Endpoints for managing users",
      "x-group": "User Management"
    }
  ],
  "paths": {
    "/users": {
      "get": {
        "tags": ["user-management"],
        "summary": "List users"
      }
    }
  }
}

在此示例中，导航分组显示为 “User Management”，但生成的页面 URL 仍使用 user-management tag 名称作为路径段。

自动填充 API 页面

在你的 docs.json 中为任意导航元素添加一个 openapi 字段，可自动生成 OpenAPI 端点页面。你可以控制这些页面在导航结构中的位置，既可作为独立的 API 区块，也可与其他页面并列展示。 openapi 字段可接受你文档仓库中的路径，或指向托管 OpenAPI 文档的 URL。

当你使用 URL 指定 OpenAPI 规范时，规范的更改不会触发 Git 推送，因此你的文档不会自动重新部署。为了保持文档同步，请在生成或更新规范的同一个 CI 操作中调用 Trigger deployment API 端点。这样你的文档就会自动更新，无需从仪表板手动触发部署。

生成的端点页面具有以下默认元数据值：

title：若存在，则取该操作的 summary 字段；若没有 summary，Mintlify 会根据 HTTP 方法与端点生成标题。
description：若存在，则取该操作的 description 字段。
version：若存在，则取父级锚点或选项卡中的 version 值。
deprecated：取该操作的 deprecated 字段。若为 true，则会在侧边导航和端点页面的端点标题旁显示“已弃用”标签。

若要将特定端点从自动生成的 API 页面中排除，请在 OpenAPI 规范中的该操作上添加 x-hidden 属性。

将端点页面添加到文档中有两种方式：

独立的 API 区块：在导航元素中引用 OpenAPI 规范以创建独立的 API 区块。
选择性端点：在导航中与其他页面并列引用特定端点。

专用 API 部分

在某个导航元素中仅添加一个 openapi 字段 (不包含其他页面) ，即可生成专用的 API 部分。规范中的所有端点都会出现在生成的部分中。

"navigation": {
  "tabs": [
    {
        "tab": "API 参考",
        "openapi": "https://petstore3.swagger.io/api/v3/openapi.json"
    }
  ]
}

若要在文档的不同部分组织多个 OpenAPI 规范，请在导航层级中将每个规范分配到不同的分组。每个分组都可以引用其各自的 OpenAPI 规范。

"navigation": {
  "tabs": [
    {
      "tab": "API 参考",
      "groups": [
        {
          "group": "用户 API",
          "openapi": {
            "source": "/path/to/users-openapi.json",
            "directory": "users-api-reference"
          }
        },
        {
          "group": "管理 API",
          "openapi": {
            "source": "/path/to/admin-openapi.json",
            "directory": "admin-api-reference"
          }
        }
      ]
    }
  ]
}

directory 字段为可选项，用于指定 Mintlify 将生成的 API 页面存放在文档仓库中的位置。若未指定，则默认使用仓库中的 api-reference 目录。

选择性端点

当你希望更精确地控制端点在文档中的展示位置时，可以在导航中引用特定端点。此方法允许你在其他内容旁生成 API 端点的页面。你也可以用这种方法将来自不同 OpenAPI 规范的端点混合在一起。

设置默认 OpenAPI 规范

为导航元素配置默认的 OpenAPI 规范，然后在 pages 字段中引用特定的端点。

"navigation": {
  "tabs": [
    {
      "tab": "快速入门",
      "pages": [
        "quickstart",
        "installation"
      ]
    },
    {
      "tab": "API 参考",
      "openapi": "/path/to/openapi.json",
      "pages": [
        "api-overview",
        "GET /users",
        "POST /users",
        "guides/authentication"
      ]
    }
  ]
}

任何符合 METHOD /path 格式的页面条目，都会基于默认的 OpenAPI 规范为该端点生成一个 API 页面。

OpenAPI 规范继承

子级导航项会继承其父级的 OpenAPI 规范，除非它们定义了自己的规范。

{
  "group": "API 参考",
  "openapi": "/path/to/openapi-v1.json",
  "pages": [
    "概述",
    "身份验证",
    "GET /users",
    "POST /users",
    {
      "group": "订单",
      "openapi": "/path/to/openapi-v2.json",
      "pages": [
        "GET /orders",
        "POST /orders"
      ]
    }
  ]
}

单个端点

通过包含文件路径，可在不设置默认 OpenAPI 规范的情况下引用特定端点。你也可以在同一文档部分中引用来自多个 OpenAPI 规范的端点。

"navigation": {
  "pages": [
    "introduction",
    "user-guides",
    "/path/to/users-openapi.json POST /users",
    "/path/to/orders-openapi.json GET /orders"
  ]
}

当你需要从不同规范中选取某些单独的端点、只想包含特定端点，或希望将端点与其他类型的文档一并呈现时，这种方法非常有用。

从你的 OpenAPI 规范创建 MDX 页面

若需对单个端点页面进行更细粒度的控制，可基于你的 OpenAPI 规范创建 MDX 页面。这样你可以自定义页面元数据与内容，并在导航中对页面重新排序或将其排除，同时仍可使用自动生成的参数与响应。有两种方式使用独立的 MDX 页面为你的 OpenAPI 规范编写文档：

在前置参数 (frontmatter) 中使用 openapi 字段为端点编写文档。
在前置参数 (frontmatter) 中使用 openapi-schema 字段为数据模型编写文档。

编写端点文档

为每个端点创建一个页面，并在 frontmatter 中使用 openapi 字段指定要展示的 OpenAPI 操作。

---
title: "Get users"
description: "Returns all plants from the system that the user has access to"
openapi: "/path/to/openapi-1.json GET /users"
deprecated: true
version: "1.0"
---

方法和路径必须与您的 OpenAPI 规范完全一致。若您有多个 OpenAPI 规范，请在引用中包含对应规范文件的路径。您也可以在 docs.json 中引用外部 OpenAPI URL。

自动生成端点页面

要根据你的 OpenAPI 规范自动生成 MDX 文件，请使用 Mintlify 的 scraper。

npx @mintlify/scraping@latest openapi-file <path-to-openapi-file> -o <folder-name>

添加 -o 标志以指定输出文件夹。若未指定文件夹，文件将生成在工作目录中。

文档数据模型

在 frontmatter 中使用 openapi-schema 字段，为 OpenAPI 规范的 components.schemas 下定义的每个数据结构各创建一个页面。

---
openapi-schema: OrderItem
---

如果在多个文件中存在同名 schema，请明确指定 OpenAPI 文件：

---
openapi-schema: en-schema.json OrderItem
---

Webhooks

Webhook 是你的 API 在事件发生时用于通知外部系统的 HTTP 回调。OpenAPI 3.1+ 文档支持 webhook。在你的 OpenAPI 文档中，与 paths 字段并列添加一个 webhooks 字段。有关定义 Webhook 的更多信息，请参阅 OpenAPI 文档中的 Webhooks。要为某个 Webhook (OpenAPI 3.1+) 创建 MDX 页面，请使用 webhook 替代某个 HTTP 方法：

---
title: "订单更新 webhook"
description: "当订单更新时触发"
openapi: "openapi.json webhook orderUpdated"
---

Webhook 名称必须与 OpenAPI 规范中 webhooks 字段中的键完全一致。

Documentation Index

​添加 OpenAPI 规范文件

​描述你的 API

​指定 API 的基础 URL

​指定身份验证

​为安全方案设置默认值

​自定义端点页面

​元数据

​内容

​href

​参数标签

​分组显示名称

​自动填充 API 页面

​专用 API 部分

​选择性端点

​设置默认 OpenAPI 规范

​OpenAPI 规范继承

​单个端点

​从你的 OpenAPI 规范创建 MDX 页面

​编写端点文档

​自动生成端点页面

​文档数据模型

​Webhooks

添加 OpenAPI 规范文件

描述你的 API

指定 API 的基础 URL

指定身份验证

为安全方案设置默认值

自定义端点页面

元数据

内容

href

参数标签

分组显示名称

自动填充 API 页面

专用 API 部分

选择性端点

设置默认 OpenAPI 规范

OpenAPI 规范继承

单个端点

从你的 OpenAPI 规范创建 MDX 页面

编写端点文档

自动生成端点页面

文档数据模型

Webhooks