Question

我有一个API在多个地方使用相同的定义，但我想在不同的地方包含不同的例子。

为了给出一些背景，我有：

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

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

我在定义上有一个例子，但有没有办法为POST /用户端点主体参数提供一个单独的示例？

Answer 1

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

您可以UserDetail使用UserCreate构造继承allOf的所有属性。在此示例中，他们共享姓名和电子邮件，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中为参数使用不同的示例值？

1 个答案: