使用 openAPI 文档中的鉴别器根据属性匹配正确的响应模式（在 swagger 等文档构建器中失败）

Question

我正在尝试在 OpenAPI (v3) 中定义有效负载模式。有效负载有两个属性：

ruleType

和

pairs

。

pairs

的模式是一个对象数组。这些对对象的模式取决于

ruleType

，它是一个枚举。

我可以在 OpenAPI 中宽松地定义它，如下所示

components:  
  schemas:
    RuleType:
      type: string
      enum: [Redirect, Cancel, Replace, Headers, UserAgent, Script, QueryParam, Response, Request, Delay]
      default: 'Redirect'
    PAYLOAD:
      type: object
      required: 
        - ruleType
      properties:
        name:
          type: string
        description:
          type: string
        ruleType:
          $ref: '#/components/schemas/RuleType'
        pairs:
          type: array
          items:
            discriminator:
              propertyName: ruleType
              mapping:
                Redirect: '#/components/schemas/RedirectRulePair'
                Cancel: '#/components/schemas/CancelRulePair'
                Replace: '#/components/schemas/ReplaceRulePair'
                Headers: '#/components/schemas/HeadersRulePair'
                UserAgent: '#/components/schemas/UserAgentRulePair'
                QueryParam: '#/components/schemas/QueryParamRulePair'
                Response: '#/components/schemas/ResponseRulePair'
                Request: '#/components/schemas/RequestRulePair'
                Delay: '#/components/schemas/DelayRulePair'
            oneOf:
              - $ref: '#/components/schemas/RedirectRulePair'
              - $ref: '#/components/schemas/CancelRulePair'
              - $ref: '#/components/schemas/ReplaceRulePair'
              - $ref: '#/components/schemas/HeadersRulePair'
              - $ref: '#/components/schemas/UserAgentRulePair'
              - $ref: '#/components/schemas/QueryParamRulePair'
              - $ref: '#/components/schemas/ResponseRulePair'
              - $ref: '#/components/schemas/RequestRulePair'
              - $ref: '#/components/schemas/DelayRulePair'
    # ... all the rule pair schemas ...

但是，当我将此文档导入到 Swagger-UI 或 Readme.com 等 API 文档生成器中时，它无法建立这种相互关系，因此即使在选择

ruleType

后，选项也太多了。 像这样：

理想情况下，由于我已经在 OpenAPI 文档中定义了映射，因此在选择

ruleType

后，

pairs

唯一可用的选项应该是映射到该

ruleType

的架构

这是否可能，有谁知道如何更好地定义它或如何在这些自动文档工具中单独定义它？对于了解 OpenAPI 规范仍然很陌生，因此任何建议都会有所帮助。谢谢！

Answer 1

这是您展示的 OpenAPI 的预期行为，API 文档工具都显示了端点的完整文档，这确实有意义。

我认为（但我没有尝试过）可以通过将模式表示为一系列 oneOf 选项来实现您所描述的目标，每个对象中具有相同的名称、描述、状态等，但是RuleType 作为 const 并且只描述相关的对结构。然后，文档工具可能会向用户显示一种模式选择，并且他们只会看到相关的模式。尝试一下 - 采用不同的方法来描述结构应该会给您一些其他选择。