在 Swagger 2 中对参数使用不同的示例值？

Question

我有一个在多个地方使用相同定义的 API，但我想为不同的地方添加不同的示例。

为了提供一些上下文，我有：

parameters:
- in: body
  description: The user object for the new user
  name: body
  schema:
    "$ref": "#/definitions/User"

其中使用了用户对象。用户登录时也会返回 User 对象，它包含比用于创建用户的信息更多的信息，例如用户 ID。

我有一个关于定义的示例，但是有没有办法可以为 POST /user 端点主体参数提供一个单独的示例？

Answer 1

我建议为用户提供两个不同的对象：UserCreate 用于创建（也可能是更新），UserDetail 由 post/put/get 返回并提供完整的详细信息。这允许不同的示例，如下所示。

您可以使用allOf 构造让UserDetail 继承UserCreate 的所有属性。在这个例子中，他们共享姓名和电子邮件，UserDetail 有一个额外的 id 和 href 属性：

paths:
  /users:
    post:
      parameters:
      - in: body
        name: body
        schema:
          $ref: '#/definitions/UserCreate'      
      responses:
        201:
          description: The created user
          schema:
            $ref: '#/definitions/UserDetail'
  /users/{id}:
    get:
      parameters:
      - in: path
        name: id
        type: string
        required: true
      responses:
        200:
          description: The user
          schema:
            $ref: '#/definitions/UserDetail'

definitions:
  UserCreate:
    properties:
      name:
        type: string
      email:
        type: string
    example:
    - name: Bob
      email: bob@somewhere.com
  UserDetail:
    allOf:
    - $ref: '#/definitions/UserCreate'
    - properties:
        id:
          type: string
        href:
          type: string
      example:
      - id: 123
        href: /users/123
        name: Bob
        email: bob@somewhere.com