在 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

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

Use different example values for parameters in Swagger 2?

documentation

swagger

swagger-2.0