Softonic

OpenAPI 必填字段检查

步 1 / 2
下一步

在把 API 描述交给同事、客户或文档生成工具之前，请确认必填字段都已就位。将文档粘贴到上方，工具会确认 version 字段、info.title、info.version 和 paths，并列出所有缺失的内容。

如何检查必填字段

  1. 1

    粘贴文档

    即使文档仍在编写中，也可以将规范以 JSON 或 YAML 格式粘贴进来。

  2. 2

    运行检查

    进入结果步骤。每个缺失的字段都会作为单独的错误显示。

  3. 3

    补充缺失内容

    使用下方的代码片段，将列出的字段添加到文件中。

  4. 4

    重新检查

    粘贴更新后的规范并再次运行，直到不再显示任何错误。

四个必需部分

字段 放置位置 示例
version 字段 顶层 openapi: 3.0.3 或 swagger: "2.0"
info.title 位于 info 内 title: Orders API
info.version 位于 info 内 version: 1.0.0
paths 顶层 paths:，至少包含第一条路由

info.version 的值是你自己 API 的版本，而不是 OpenAPI 规范的版本。由于规范版本已经写在顶部，很多人会忘记填写这一项。

全部缺失的示例

servers:
  - url: https://api.example.com

这个小文档不包含任何必需部分。报告会列出三个错误：

检查结果 类型
Missing ‘openapi’ or ‘swagger’ version field. 错误
Missing ‘info’ object. 错误
Missing ‘paths’ object. 错误

当整个 info 对象缺失时，工具只报告这一个错误，不会另外单独列出 title 和 version。补充带有这两个字段的 info 后，下一次运行会报告其中仍然缺失的字段。

起始骨架

openapi: 3.0.3
info:
  title: Orders API
  version: 1.0.0
paths:
  /orders:
    get:
      summary: List orders

这个骨架可以通过所有必填字段检查。将名称替换为你自己的内容，然后在此基础上继续构建。响应、架构和安全性不属于本检查范围。

何时运行此检查

在从零开始编写新规范时、从代码生成规范后，以及把规范发给需要导入到其他工具的人之前，都应运行此检查。许多导入工具遇到第一个缺失的必填字段就会以简短消息停止，因此一次性发现全部问题可以减少来回修改的次数。对于经常忘记 info.version 或在草拟时留空 paths 的新手来说，这也是一个很有用的提醒。

必填字段通过之后，接下来有用的补充包括 info 下的简短 description、一个 servers 条目，以及每个操作上的 operationId。本检查不会验证这些内容，但它们能让规范更易读，也更容易转换为客户端代码。

常见问题

不是。openapi 字段说明你使用的规范版本，而 info.version 是你自己 API 的版本，例如 1.0.0。

该键必须存在且为对象，但本检查并不要求其中包含路由。发布前请添加真实的路由。

title 和 version 的检查只有在 info 对象存在时才会运行。请先添加 info，然后重新运行，以查看其字段是否完整。

不会。这里只要求 version 字段、info、title、version 和 paths。操作级别的细节不在检查范围内。

相关工具

Webpack 配置生成器

为纯 JavaScript、React 或 Vue 项目生成 webpack 5 的 webpack.config.js：支持 TypeScript、Babel、CSS 或 Sass、图片、HtmlWebpackPlugin、开发服务器，并给出 npm install 命令。

ASCII 表参考

完整 ASCII 表，覆盖 0 到 127；列出每个代码的十进制、十六进制、八进制、二进制值和 HTML 数字字符引用写法，包括 NUL、LF、DEL。

Protocol Buffers 解码器

在浏览器中解码 hex、Base64、Base64URL、文本或文件中的 Protobuf 线格式字节，准确检查字段候选解释并导出私密报告。

XML 格式化工具

以一致的缩进美化 XML 文档，并精确定位到行号，捕获格式良好性错误。

HTML 字符参考

可搜索的 HTML 实体列表，含命名代码与数值代码，并支持一键复制特殊字符和符号。

文件大小转换器

在字节、KB、MB、GB、TB及IEC二进制单位（KiB、MiB、GiB、TiB）之间转换，可自由组合十进制与二进制。

此工具还提供其他语言版本

使用指南与应用场景