swagger - Swagger / OpenAPI - Diffrent model representations depending on authorization level

Question

How do i use the Swagger models when i have diffrent representations for each model depending on the authorization level.

For example, a country model for an administrator looks like this:

definitions:
  Country:
    type: object
    properties:
      id:
        type: integer
        format: int64
      name:
        type: string
        example: The Netherlands
      code:
        type: string
        example: NL
      created_at:
        type: string
        example: 2017-06-01 13:37:00
      updated_at:
        type: string
        example: 2017-06-01 14:00:00

However, just a regular user model looks like this

definitions:
  Country:
    type: object
    properties:
      id:
        type: integer
        format: int64
      name:
        type: string
        example: The Netherlands
      code:
        type: string
        example: NL

I was considering to place the model definitions in the response like this:

/admin/countries/{countryId}:
    get:
      tags:
        - AdminCountries
      summary: Find a country by ID
      operationId: adminCountriesGetById
      security:
        - Bearer: []
      parameters:
        - in: path
          type: integer
          format: int64
          name: countryId
          required: true
      responses:
        '200':
          description: Success
          schema:
            type: object
            properties:
              id:
                type: integer
                format: int64
              name:
                type: string
                example: The Netherlands
              code:
                type: string
                example: NL
              created_at:
                type: string
                example: 2017-06-01 13:37:00
              updated_at:
                type: string
                example: 2017-06-01 14:00:00

I am not really sure if my "solution" is the correct way to handle this.

Answer 1

即将到来的 OpenAPI 规范 3.0 将支持oneOf定义多个可能的请求/响应主体。

在 2.0 中，您最多可以将特定于管理员的属性定义为可选的，并用于description记录这些属性只为管理员返回，而不是为普通用户返回。