Swagger / OpenAPI - 不同的模型表示取决于授权级别

Question

当我根据授权级别对每个模型有不同的表示时，我如何使用 Swagger 模型。

例如，管理员的国家/地区模型如下所示：

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

但是，普通用户模型看起来像这样

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

我正在考虑像这样在响应中放置模型定义：

/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

我不确定我的 "solution" 是否是处理此问题的正确方法。

Answer 1

即将发布的 OpenAPI 规范 3.0 将支持 oneOf 定义多个可能的 request/response 主体。

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

Swagger / OpenAPI - 不同的模型表示取决于授权级别

Swagger / OpenAPI - Diffrent model representations depending on authorization level

swagger

openapi