API设计文档后端【免费下载链接】OpenAPI-SpecificationThe OpenAPI Specification Repository项目地址https://gitcode.com/gh_mirrors/op/OpenAPI-Specification点击查看免费下载本指南以 OpenAPI-Specification 仓库中_archive_/schemas/归档目录为核心系统梳理 OpenAPI前身 Swagger各版本 JSON Schema 文件的来龙去脉包括 v1.2 时代由社区捐赠的 Schema 集合、可经 NPM 安装的 v2.0 Schema、以及以 YAML 为源、带迭代日期并发布到 spec.openapis.org 的 v3.0 验证体系。读完本文你将掌握这些 Schema 文件的结构、能力边界、测试方式与改进流程并能判断在何种场景下该使用归档版本还是现行版本。归档目录定位旧版 JSON Schema 的权威说明_archive_/schemas/README.md是该归档目录的入口文档它首先明确了两个关键事实该目录存放的是过时的 JSON Schema 文件Archive of outdated JSON Schema Files覆盖 Swagger/OpenAPI 的 v1.2、v2.0 与 v3.0 三个时代该目录不再维护不应用于生产环境。归档声明原文以醒目的[!CAUTION]强调Schema files in this folder are not maintained any more and are not intended for productive use.同时文档以[!TIP]提示了正确的替代路径使用当前 OpenAPI 版本进行校验的 JSON Schema 可在 spec.openapis.org 获取这些现行 Schema 文件维护在仓库中对应vX.Y-dev分支的src/schemas文件夹内见 spec.config.json 中schemas字段对meta.yaml、dialect.yaml、schema.yaml、schema-base.yaml的引用。因此阅读本文时请始终记住两条分界线归档 vs 现行归档仅供历史研究与迁移参考、规范 vs SchemaSchema 永远只是规范的机器可读投影而非规范的权威来源。Swagger 1.2社区捐赠的开山之作历史背景_archive_/schemas/v1.2/README.md记载了这段历史Swagger 规范 JSON Schema 的工作由 Francis Galiegue 捐赠给社区。这是 OpenAPI 生态最早的一批机器可读校验文件彼时规范还叫作 Swagger版本号为 1.2。该 README 同时坦诚地指出一个伴随始终的局限由于 JSON Schema 本身的表达能力限制并非所有约束都能被描述。这句话在 v1.2 时代就已出现并在 v3.0 的 README 中被反复强调——它奠定了整个归档目录的技术基调Schema 是尽力而为的校验工具永远无法完全替代人对规范文本的解读。目录构成两分法的资源清单与 API 声明_archive_/schemas/v1.2/目录下共有 12 个 JSON 文件构成了 Swagger 1.2 时代的完整 Schema 家族文件职责resourceListing.json资源清单Resource Listing的根 Schemarequired: [swaggerVersion, apis]swaggerVersion枚举固定为1.2通过$ref引用resourceObject.json、infoObject.json、authorizationObject.jsonapiDeclaration.jsonAPI 声明API Declaration根 Schemarequired: [swaggerVersion, basePath, apis]basePath要求format: uri且匹配^https?://内部定义apiObject、mimeTypeArray等resourceObject.json资源对象声明单条 API 资源的path与operationsoperationObject.json操作对象描述 HTTP 方法与参数、响应parameterObject.json参数对象dataType.json/dataTypeBase.json数据类型定义与基类modelsObject.json模型集合infoObject.json信息对象标题、版本、描述、联系方式等authorizationObject.json授权对象oauth2GrantType.jsonOAuth2 授权类型枚举值得注意的细节以 apiDeclaration.json 为例它顶部使用additionalProperties: false收紧字段边界且通过相对$ref如$ref: modelsObject.json#、$ref: authorizationObject.json#在多个文件之间互相关联——这正是现代 OpenAPI 组件化、多文件组织的早期雏形。OpenAPI 2.0可通过 NPM 安装的官方 Schema安装方式_archive_/schemas/v2.0/README.md是三个版本 README 中最简洁的它给出了 v2.0 Schema 的官方获取方式——通过 NPM 安装npm install --save swagger-schema-official安装后即可在 Node.js 项目中以标准方式引用schema.json对 Swagger/OpenAPI 2.0 文档进行 JSON Schema 校验。该 Schema 的许可证为Apache-2.0这一点与仓库根目录的 LICENSE 及 package.json 中license: Apache-2.0保持一致。结构速览_archive_/schemas/v2.0/schema.json共 1600 余行的头部结构揭示了 v2.0 校验的核心规则{ title: A JSON Schema for Swagger 2.0 API., id: http://swagger.io/v2/schema.json#, $schema: http://json-schema.org/draft-04/schema#, type: object, required: [swagger, info, paths], additionalProperties: false, patternProperties: { ^x-: { $ref: #/definitions/vendorExtension } }, properties: { swagger: { type: string, enum: [2.0] }, info: { $ref: #/definitions/info }, host: { type: string, pattern: ^[^{}/ :\\\\](?::\\d)?$ }, basePath: { type: string, pattern: ^/ }, schemes: { $ref: #/definitions/schemesList } } }关键约束包括采用JSON Schema draft-04$schema字段v1.2 与 v3.0 归档 Schema 也统一使用 draft-04根对象required三个字段swagger枚举固定2.0、info、pathsadditionalProperties: false拒绝未声明字段通过patternProperties: ^x-为扩展字段vendor extension预留入口这也解释了为何归档 Schema 中大量对象都同时具备patternProperties: ^x-: {}与additionalProperties: false的组合——只允许规范的字段加上x-前缀的扩展。OpenAPI 3.0以 YAML 为源、带迭代日期的发布体系_archive_/schemas/v3.0/README.md是归档目录中信息量最大的文档它描述了一套与现代 OpenAPI 生态接轨的 Schema 生产与发布机制。_archive_/schemas/v3.0/目录结构如下schema.yaml唯一维护的源文件1031 行完整 JSON Schema draft-04 定义schema.test.mjsSchema 的自动化测试入口pass/6 个应当通过校验的示例文档petstore.yaml、petstore-expanded.yaml、callback-example.yaml、link-example.yaml、api-with-examples.yaml、uspto.yaml。生产与发布管线v3.0 的 Schema 并非手写 JSON而是遵循YAML 源 → 生成 JSON → 发布到 spec 站点的管线schema.yaml是唯一编辑源其id为https://spec.openapis.org/oas/3.0/schema/WORK-IN-PROGRESSREADME 明确指出带有WORK-IN-PROGRESS标识的源文件不供直接使用生成的 JSON Schema 发布在 spec.openapis.org由于 GitHub Pages 的限制spec 站点上的 Schema 以Content-Type: application/octet-stream提供消费方应将其按application/schemajson解释——这对直接拉取 Schema 做校验的工具链是一个重要提示。迭代日期id 机制这是 v3.0 Schema 最独特的机制发布到 spec 站点的 Schema 在其id中带有迭代日期iteration date使得同一发布线如 3.0的 Schema 可以独立于规范补丁patch发布周期进行更新。例如id: https://spec.openapis.org/oas/3.0/schema/2019-04-02表示该迭代创建于2019 年 4 月 2 日。在 GitHub 上进行了一次于 2019 年提出的设计讨论探讨如何以编程方式确定每个 Schema 的最新日期在此之前最可靠的做法是直接读取id字段解析日期。能力边界Schema 不是规范的权威v3.0 README 用一整节阐述Improving the schema的边界这是任何将 Schema 用于生产校验的人都必须理解的原则规范优先JSON Schema 不是规范的事实来源source of truth。当规范文本与 JSON Schema 冲突时以规范为准表达力有限部分规范约束无法用 JSON Schema 表示因此强烈建议辅以其他方法确保合规只校验强制方面Schema 仅验证 OAS 的强制mandatory要求可选的字段用法、未定义或会被忽略的行为不在校验范围内用于额外可选校验的 Schema 方案当时仍处于讨论之中。从源码看这一边界在 schema.yaml 中体现得很具体例如根级required: [openapi, info, paths]与openapi字段的pattern: ^3\.0\.\d(-.)?$L5-L12只锁定了文档必备的最小骨架而大量语义约束如响应码与操作的业务含义只能依赖人对规范的理解。核心结构剖析schema.yaml以 JSON Schema draft-04 书写definitions中定义的引用对象构成了完整的 3.0 数据模型可归纳为几大族根对象与基础组件Inforequired: [title, version]、Contact、Licenserequired: [name]、Serverrequired: [url]、ServerVariablerequired: [default]、ExternalDocumentationrequired: [url]、Tagrequired: [name]、Referencerequired: [$ref]$ref需为format: uri-reference。Components 八大容器Components定义了对schemas、responses、parameters、examples、requestBodies、headers、securitySchemes、links、callbacks共九类可复用组件的模式键名需匹配^[a-zA-Z0-9\.\-_]$每个条目在具体定义与引用之间二选一oneOf。Schema 对象Schema是核心定义L203-L333覆盖数值约束multipleOf/maximum/exclusiveMaximum/minimum/exclusiveMinimum、字符串约束maxLength/minLength/pattern、数组约束maxItems/minItems/uniqueItems、对象约束maxProperties/minProperties/required、组合关键字not/allOf/oneOf/anyOf、type枚举array/boolean/integer/number/object/string以及 3.0 特有字段nullable、discriminator、readOnly、writeOnly、deprecated、xml、example。其additionalProperties: false配合patternProperties: ^x-: {}精确限定了 Schema 对象的合法字段集合。路径与操作Paths只接受以/开头的路径键patternProperties: ^\/PathItem列出get/put/post/delete/options/head/patch/trace全部 HTTP 方法及$ref、summary、servers、parametersOperation强制required: [responses]Responses通过^1-5$校验状态码含default与XX通配并minProperties: 1。参数四种变体Parameter统一要求name、in再通过oneOf分派到PathParameterstyle限 matrix/label/simplerequired强制为true、QueryParameterstyle 限 form/spaceDelimited/pipeDelimited/deepObject、HeaderParameterstyle 限 simple、CookieParameterstyle 限 form——从源码结构可以推断参数语义如路径参数必须 required被内嵌进了 Schema 而非依赖外部检查。安全方案SecurityScheme用oneOf分派到四种类型APIKeySecuritySchemetype: apiKeynamein枚举 header/query/cookie、HTTPSecuritySchemetype: http并通过pattern: ^[Bb][Ee][Aa][Rr][Ee][Rr]$区分 Bearer 与非 Bearer、OAuth2SecuritySchemerequired: [type, flows]、OpenIdConnectSecuritySchemerequired: [type, openIdConnectUrl]。OAuthFlows则定义了implicit、password、clientCredentials、authorizationCode四种流。互斥约束的 Schema 化表达这是JSON Schema 表达规范约束的精妙示例全部用notrequired实现ExampleXORExamplesL633-L636example与examples互斥SchemaXORContentL638-L656schema与content二选一且选了content后禁止style/explode/allowReserved/example/examplesLink的operationId与operationRef互斥not: required: [operationId, operationRef]HTTPSecurityScheme内部对 Bearer / Non-Bearer 的分支约束。附带的示例文档pass/目录中的样例既是文档示例也是测试夹具可用于快速理解 3.0 文档结构petstore.yaml经典 Petstore展示了openapi: 3.0.0、info、servers、paths、components.schemasPet/Pets/Error的完整骨架以及 path 参数、query 参数、$ref引用、默认响应等常规写法callback-example.yaml演示回调机制——callbacks中onData使用{$request.query.callbackUrl}/data运行时表达式把回调地址指向请求参数link-example.yaml演示links通过$ref引用#/components/links/...建立响应到后续操作的关联另有api-with-examples.yaml、petstore-expanded.yaml、uspto.yaml供学习。自动化测试Schema 如何被验证v3.0 README 提到测试套件属于包的一部分并给出命令npm install npm test在仓库中测试由两处协同完成1. 归档 Schema 自身测试archive/schemas/v3.0/schema.test.mjs 读取schema.yaml构建校验器然后遍历pass/目录下所有.yaml文件逐个断言output.valid true。从代码看L31-L43它依赖oai/build-infra提供的validate、YAML.parse、buildSchemaDocument等基础设施并注册了application/schemayaml媒体类型插件以解析 YAML 形式的 Schema。2. 仓库级 Schema 测试配置tests/schema/oas-schema.mjs 通过createTestConfig为 3.0 Schema 的校验注册了 OpenAPI 自定义词汇关键字——discriminator、example、externalDocs、xml——它们的 URI 均指向https://spec.openapis.org/oas/3.0/keyword/...用于把 OAS 扩展关键字映射到标准 JSON Schema 校验流程中vitest.config.mjs 则将其作为全局 setup 载入。结合 package.json 的脚本test: oai-spec-test、build: oai-spec-build可以推断Schema 的发布流程与测试流程在 CI 中是一体的改动 Schema 必须同步通过测试。改进流程向官方提交 Schema 修正的正确姿势v3.0 README 给出了清晰的贡献路径面向希望改善官方 Schema 的开发者提交 PR 到main分支修改schema.yaml源文件并为改动添加测试用例归档版本的测试即 schema.test.mjs对应的现行版本测试位于tests/schema/下由TSC技术指导委员会依次执行对更新后的 Schema 运行测试 → 更新迭代版本即id中的日期→ 发布新版本。整个流程与迭代日期机制环环相扣正因为 Schema 可以独立于规范版本迭代TSC 才能在任意时间点修正 Schema 缺陷并发布新迭代而不必等待下一个规范补丁发布。从 spec.config.json 的release配置可以看到正式发布分支上会移除src、tests/schema/pass、tests/schema/fail、tests/schema/schema.test.mjs等内部构件——再次印证Schema 源文件YAML与发布产物JSON分离的设计。选择指南何时使用归档何时使用现行 Schema综合整个归档目录的信息可给出如下决策建议场景推荐 Schema校验 OAS 2.0Swagger 2.0文档_archive_/schemas/v2.0/schema.json或 NPM 包swagger-schema-official注意其为 draft-04校验 OAS 3.0.x 文档历史研究、离线环境_archive_/schemas/v3.0/schema.yaml生成的 JSON迭代日期机制注意WORK-IN-PROGRESS源不可直接使用校验现行 OpenAPI 版本的文档生产环境spec.openapis.org 上按版本发布的 Schema维护于对应vX.Y-dev分支的src/schemas目录理解 Swagger 1.2 时代的多文件 Schema 组织_archive_/schemas/v1.2/下 12 个 JSON 文件及其关联关系最后再回到归档 README 的两条核心警告归档目录中的 Schema 已停止维护、不应用于生产当规范文本与 Schema 冲突时永远以规范文本为准。在 OpenAPI 生态中JSON Schema 是机器可读的校验助手而 versions/ 目录下的规范文本如 3.0.4.md才是最终的权威依据——理解这一关系是正确使用 OpenAPI Schema 的前提。赞分享API设计文档后端【免费下载链接】OpenAPI-SpecificationThe OpenAPI Specification Repository项目地址https://gitcode.com/gh_mirrors/op/OpenAPI-Specification点击查看免费下载相关推荐go-openapi/validate 详解基于 moby 仓库实践 Swagger 2.0OpenAPI 2.0规范与 JSON Schema Draft 4 校验go openapi/validate 详解基于 moby 仓库实践 Swagger 2.0OpenAPI 2.0规范与 JSON Schema Draf云原生容器运行时虚拟化容器编排Medusa OAS CLI 完全指南从 JSDoc 注解生成、校验到发布 OpenAPI 规范Medusa OAS CLI 完全指南从 JSDoc 注解生成、校验到发布 OpenAPI 规范 Medusa 开源仓库为开发者提供了一套名为 medusa后端电商前端Swagger Parser高效解析验证Swagger与OpenAPI规范的专业工具Swagger Parser高效解析验证Swagger与OpenAPI规范的专业工具 在API驱动的现代软件开发中规范化的API文档管理已成为项目成功的关键开发工具创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考