如何在application/x-www-form-urlencoded请求体中添加$ref引用？

我已经构建了可正常工作的JSON请求，但当请求媒体类型为application/x-www-form-urlencoded时，不知道该如何正确使用$ref引用Schema。

举个例子：我已经创建了Filters Schema，希望在NewDogRequest.Filter参数里引用它。最初的OpenAPI YAML代码如下：

openapi: 3.0.2
info:
  description: RESTful web services for writing and reading Dogs Data.
  version: v1.0
  title: Dogs Services
tags:
  - name: Dogs
paths:
  /dogs:
    post:
      tags:
        - Dogs
      summary: Add new dogs data.
      description: Use this service when you want to add a new dog.
      operationId: addDog
      requestBody:
        $ref: '#/components/requestBodies/NewDogRequest'
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                  type: string

components:
  # ****************** Request Bodies ****************** #
  requestBodies:
    NewDogRequest:
      content:
        application/x-www-form-urlencoded:
          schema:
            type: object
            properties:
              dogID:
                description: >
                  * Unique dog id.
                type: string
             
              filter:
                description: >
                  Specifies the type breed of the dog
                type: string
                enum:
                  - German Sheperd
                  - Husky
                  - DashHound
                default: German Sheperd

  # ****************** Schemas ****************** #
  schemas:
    Filters:
      type: string
      enum:
        - German Sheperd
        - Husky
        - DashHound
      default: German Sheperd

我尝试直接用$ref引用，但枚举值没有在Swagger UI的HTML界面中渲染出来，写法如下：

requestBodies:
    NewDogRequest:
      content:
        application/x-www-form-urlencoded:
          schema:
            type: object
            properties:
              dogID:
                description: >
                  * Unique dog id.
                type: string
             
              filter:
                description: >
                  Specifies the type breed of the dog
                $ref: '#/components/schemas/Filters'

问题出在：OpenAPI规范中，$ref会覆盖同级的所有其他字段（比如你写的description），而且Swagger UI在处理application/x-www-form-urlencoded类型的请求体时，直接用$ref引用属性的渲染逻辑存在兼容问题。可以用以下两种方法解决：

方法1：将描述移到引用的Schema中 #

把filter字段的description直接放到Filters Schema里，这样引用时就能自动带上描述和枚举定义：

openapi: 3.0.2
info:
  description: RESTful web services for writing and reading Dogs Data.
  version: v1.0
  title: Dogs Services
tags:
  - name: Dogs
paths:
  /dogs:
    post:
      tags:
        - Dogs
      summary: Add new dogs data.
      description: Use this service when you want to add a new dog.
      operationId: addDog
      requestBody:
        $ref: '#/components/requestBodies/NewDogRequest'
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                  type: string

components:
  requestBodies:
    NewDogRequest:
      content:
        application/x-www-form-urlencoded:
          schema:
            type: object
            properties:
              dogID:
                description: >
                  * Unique dog id.
                type: string
             
              filter:
                $ref: '#/components/schemas/Filters'

  schemas:
    Filters:
      description: >
        Specifies the type breed of the dog
      type: string
      enum:
        - German Sheperd
        - Husky
        - DashHound
      default: German Sheperd

方法2：用allOf合并引用和本地描述 #

如果不想修改Filters Schema，可以使用allOf关键字，把$ref和本地的description合并起来，这样既保留了自定义描述，又能引用枚举定义：

openapi: 3.0.2
info:
  description: RESTful web services for writing and reading Dogs Data.
  version: v1.0
  title: Dogs Services
tags:
  - name: Dogs
paths:
  /dogs:
    post:
      tags:
        - Dogs
      summary: Add new dogs data.
      description: Use this service when you want to add a new dog.
      operationId: addDog
      requestBody:
        $ref: '#/components/requestBodies/NewDogRequest'
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                  type: string

components:
  requestBodies:
    NewDogRequest:
      content:
        application/x-www-form-urlencoded:
          schema:
            type: object
            properties:
              dogID:
                description: >
                  * Unique dog id.
                type: string
             
              filter:
                description: >
                  Specifies the type breed of the dog
                allOf:
                  - $ref: '#/components/schemas/Filters'

  schemas:
    Filters:
      type: string
      enum:
        - German Sheperd
        - Husky
        - DashHound
      default: German Sheperd

两种方法都能让Swagger UI正确渲染出filter字段的枚举选项。

内容的提问来源于stack exchange，提问作者Warren D'souza