swagger - 我可以分离出组合模式并在 OpenAPI 中引用它吗？

Question

一些背景：我在 openapi-codegenerator 遇到了一些问题，我得到的建议之一是：

分离出组合模式并在 OpenAPI 中引用它，将组合模式移动到一个组件中，并在响应中 $refing 它：

components:
  ResponseOneOfSchema:
    oneOf:
     - $ref to IdentityProblemDetails
     - $ref to LanguageUsageProblemDetails

然后在响应中，$ref 到 ResponseOneOfSchema。

我对这个最小的有效工作示例模式的实际问题是，这两个在 OpenAPI 3.0 中是否等效（根据swagger-validator似乎都是有效的）？

---
openapi: 3.0.0
info:
  title: Dummy API
  version: 0.1.0
  description: |
    Some description about the Dummy API here...

paths:
  /pets:
    patch:
      requestBody:
        content:
          application/json:
            schema:
              oneOf:
                - $ref: '#/components/schemas/Cat'
                - $ref: '#/components/schemas/Dog'
      responses:
        '200':
          description: Updated
components:
  schemas:
    Dog:
      type: object
      properties:
        bark:
          type: boolean
        breed:
          type: string
          enum: [Dingo, Husky, Retriever, Shepherd]
    Cat:
      type: object
      properties:
        hunts:
          type: boolean
        age:
          type: integer

和

---
openapi: 3.0.0
info:
  title: Dummy API
  version: 0.1.0
  description: |
    Some description about the Dummy API here...

paths:
  /pets:
    patch:
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OneOfCatDogSchema'
      responses:
        '200':
          description: Updated
components:
  schemas:
    OneOfCatDogSchema:
      oneOf:
        - $ref: '#/components/schemas/Cat'
        - $ref: '#/components/schemas/Dog'
    Dog:
      type: object
      properties:
        bark:
          type: boolean
        breed:
          type: string
          enum: [Dingo, Husky, Retriever, Shepherd]
    Cat:
      type: object
      properties:
        hunts:
          type: boolean
        age:
          type: integer

如果它们确实是等价的，如果还有其他属性oneOf（我应该用 包裹它们allOf）怎么办？

  allOf:
    - $ref: '#/components/schemas/composedSchemaForOneOf'
    - type: object

喜欢

---
openapi: 3.0.0
info:
  title: Dummy API
  version: 0.1.0
  description: |
    Some description about the Dummy API here...

paths:
  /pets:
    patch:
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AnimalSpec'
      responses:
        '200':
          description: Updated
components:
  schemas:
    AnimalSpec:
      type: object
      description: The description of the config
      properties:
        display_name:
          type: string
          description: The name of the animal.
          example: 
        config:
          description: |
            The description of the config
          default: {kind: Cat}
          example: {kind: Cat}
          discriminator:
            propertyName: kind
            mapping:
              Cat: '#/components/schemas/Cat'
              Dog: '#/components/schemas/Dog'
          oneOf:
            - $ref: '#/components/schemas/Cat'
            - $ref: '#/components/schemas/Dog'
    Dog:
      type: object
      properties:
        bark:
          type: boolean
        breed:
          type: string
          enum: [Dingo, Husky, Retriever, Shepherd]
    Cat:
      type: object
      properties:
        hunts:
          type: boolean
        age:
          type: integer

->

---
openapi: 3.0.0
info:
  title: Dummy API
  version: 0.1.0
  description: |
    Some description about the Dummy API here...

paths:
  /pets:
    patch:
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AnimalSpec'
      responses:
        '200':
          description: Updated
components:
  schemas:
    AnimalSpec:
      type: object
      description: The description of the config
      properties:
        display_name:
          type: string
          description: The name of the animal.
          example: 
        config:
          description: |
            The description of the config
          default: {kind: Cat}
          example: {kind: Cat}
          discriminator:
            propertyName: kind
            mapping:
              Cat: '#/components/schemas/Cat'
              Dog: '#/components/schemas/Dog'
          $ref: '#/components/schemas/OneOfCatDogSchema'
    OneOfCatDogSchema:
      oneOf:
        - $ref: '#/components/schemas/Cat'
        - $ref: '#/components/schemas/Dog'
    Dog:
      type: object
      properties:
        bark:
          type: boolean
        breed:
          type: string
          enum: [Dingo, Husky, Retriever, Shepherd]
    Cat:
      type: object
      properties:
        hunts:
          type: boolean
        age:
          type: integer

我已经根据swagger-parser验证了我在此处发布的所有 4 个规范都是有效的规范。

标签： swaggeropenapiopenapi-generator