OpenAPI 设置 - Another Horizon

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

添加 OpenAPI 规范文件

要使用 OpenAPI 为你的端点撰写文档，你需要一个或多个有效的 OpenAPI 规范文件，格式为 JSON 或 YAML，并且遵循 OpenAPI 3.0+ 规范。将 OpenAPI 规范添加到你的文档存储库中，或将其托管在线，以便你可以通过 URL 访问这些规范。在 docs.json 的 navigation 配置中引用任意数量的 OpenAPI 规范，以为你的 API 端点创建页面。每个规范文件都会生成自己的一组端点。

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

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

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

描述你的 API

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

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

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。

自定义端点页面

在 OpenAPI 规范中添加 x-mint 扩展即可自定义端点页面。x-mint 扩展可让你更精细地控制 API 文档的生成与展示。

元数据

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

{
  "paths": {
    "/users": {
      "get": {
        "summary": "获取用户",
        "description": "获取用户列表",
        "x-mint": {
          "metadata": {
            "title": "列出所有用户",
            "description": "获取分页用户数据及筛选选项",
            "og:title": "显示用户列表"
          }
        },
        "parameters": [
          {
            // 参数配置
          }
        ]
      }
    }
  }
}

内容

使用 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 时，导航项将直接链接到指定的 URL，而不会生成 API 页面。

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

自动填充 API 页面

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

title：若存在，则取该操作的 summary 字段；若没有 summary，则根据 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 字段为可选项，用于指定生成的 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 规范会沿导航层级向下继承。子级导航项会继承其父级的 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"
---

---
title: "title of the page"
description: "description of the page"
openapi: openapi-file-path method path
deprecated: boolean (not required)
version: "version-string" (not required)
---

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

自动生成端点页面

要根据你的 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
---

---
openapi-schema: "openapi-file-path schema-key"
---

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

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

---
openapi-schema: "path-to-schema-file schema-key"
---

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 字段中的键完全一致。

​添加 OpenAPI 规范文件

​描述你的 API

​指定 API 的基础 URL

​指定身份验证

​自定义端点页面

​元数据

​内容

​Href

​自动填充 API 页面

​专用 API 部分

​选择性端点

​设置默认 OpenAPI 规范

​OpenAPI 规范继承

​单个端点

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

​编写端点文档

​自动生成端点页面

​文档数据模型

​Webhooks

添加 OpenAPI 规范文件

描述你的 API

指定 API 的基础 URL

指定身份验证

自定义端点页面

元数据

内容

Href

自动填充 API 页面

专用 API 部分

选择性端点

设置默认 OpenAPI 规范

OpenAPI 规范继承

单个端点

从你的 OpenAPI 规范创建 MDX 页面

编写端点文档

自动生成端点页面

文档数据模型

Webhooks