如何在OpenAPI 3 YAML文件的paths段使用多引用？

核心问题原因 #

OpenAPI规范中，每个路径（如/blog）是一个对象，其中HTTP方法（get/post/delete等）是唯一键。你之前尝试的多$ref、自定义$ref1、allOf都不符合路径层级的结构要求，因此会触发验证错误。

可行解决方案 #

方案1：通过中间整合文件聚合方法

为每个路径创建一个中间文件，将该路径下的所有HTTP方法引用整合在一起，再让主文件引用这个中间文件。

1. 主文件openapi.yml的paths段修改：

openapi: "3.0.0"
info:
  version: 1.0.0
  title: Swagger Petstore
  description: Multi-file boilerplate for OpenAPI Specification.
  license:
    name: MIT
servers:
  - url: http://example.swagger.io/v1
paths:
  /blog:
    $ref: './routes/blog/blog-main.yml'
  /blog/{id}:
    $ref: './routes/blog/blog-id-main.yml'

2. 创建./routes/blog/blog-main.yml：

get:
  $ref: './get-all.yml'
post:
  $ref: './create.yml'

3. 创建./routes/blog/blog-id-main.yml：

get:
  $ref: './show.yml'
put:
  $ref: './update.yml'
delete:
  $ref: './delete.yml'

方案2：主文件直接引用方法级文件

省去中间整合文件，直接在主文件的路径下为每个HTTP方法单独引用对应的拆分文件：

主文件openapi.yml的paths段修改：

openapi: "3.0.0"
info:
  version: 1.0.0
  title: Swagger Petstore
  description: Multi-file boilerplate for OpenAPI Specification.
  license:
    name: MIT
servers:
  - url: http://example.swagger.io/v1
paths:
  /blog:
    get:
      $ref: './routes/blog/get-all.yml'
    post:
      $ref: './routes/blog/create.yml'
  /blog/{id}:
    get:
      $ref: './routes/blog/show.yml'
    put:
      $ref: './routes/blog/update.yml'
    delete:
      $ref: './routes/blog/delete.yml'

以上两种方式都符合OpenAPI规范，swagger-cli可以正常打包合并，且保持了文件拆分的粒度。

内容的提问来源于stack exchange，提问作者netdjw