在OpenAPI中设置参数规则

Question

我开始使用 YAML 学习 API 文档。我有下面的 YAML，我的查询参数是

id

、

firstName

和

lastName

。用户应提供

id

或

firstName

或

lastName

中的任何一个。

1. 如果提供了

   id

   ，则无需提供

   lastName

   和

   firstName

2. 如果提供了

   lastName

   或

   firstName

   ，则无需提供

   id

有些喜欢

id

或（

firstName

或

lastName

）。

那么我如何在 YAML 中定义此规则。我认为

oneOf

、

anyOf

构造可以在请求正文中用于相同的用途，但如何在查询参数中实现此目的？

openapi: 3.0.1
info:
  title: Example API
  version: 1.0.0
paths:
  /users:
    get:
      summary: Get user information by ID or name
      parameters:
        - name: id
          in: query
          schema:
            type: integer
          required: false
          description: User ID
        
        - name: firstName
          in: query
          schema:
            type: string
          required: false
          description: First name of the user
        
        - name: lastName
          in: query
          schema:
            type: string
          required: false
          description: Last name of the user
      
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: string
                example: User information retrieved successfully

        '400':
          description: Bad request
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Invalid request parameters

Answer 1

当前形式的 OpenAPI 不支持此功能。

已经有一些关于将查询参数编码为架构对象的讨论，然后您可以使用您提到的 JSON 架构构造.. oneOf 或 anyOf

这不太可能得到许多工具的支持，因为直到最近才开始考虑它

这个想法是您定义一个参数，工具可以将其解析为模式并使用

explode: true, style: form

提取属性。

你可以尝试一下

openapi: '3.0.3'
info:
  title: test
  version: '1'
paths:
  '/thing':
    parameters:
      - name: query_prop_name
        in: query
        style: form
        explode: true
        schema:
          oneOf:
            - required:
                - id
              type: object
              properties:
                id:
                  type: integer
              additionalProperties: false
            - required:
                - firstName
                - lastName
              type: object
              properties:
                firstName:
                  type: string
                lastName:
                  type: string
              additionalProperties: false

---

您最终会收到这样的请求

GET /thing?id=1 HTTP/1.1

或

GET /thing?firstName=test&lastName=thing HTTP/1.1