swagger limit 响应的错误代码

Question

我正在处理一个 swagger 2.0 文件，我想在其中指定我的响应中的错误代码只能是 USERNAME_VALIDATION_FAILED 或 EMAIL_VALIDATION_FAILED。这是由于 swaggerfile 的 swagger-ui 视图，其中每个响应错误都可以具有错误代码枚举中定义的 20 个错误代码。如何限制特定响应的可能错误代码？

在我的 swaggerfile 中有请求

/register:
post:
  ...
  parameters:
      ...
  responses:
    ...
    400:
      description: Username or email validation failed, possible values for code are USERNAME_VALIDATION_FAILED, EMAIL_VALIDATION_FAILED
      schema:
        $ref: '#/definitions/Error'

我的错误看起来像

Error:
type: object
properties:
  code:
    type: string
    enum:
      - USERNAME_VALIDATION_FAILED
      - EMAIL_VALIDATION_FAILED
      - USERNAME_EXISTS
      - ...

我会建议类似

schema:
  $ref: '#/definitions/Error.code.of(USERNAME_VALIDATION_FAILED, EMAIL_VALIDATION_FAILED)'

Answer 1

您无法覆盖属性的 enum，因此您需要一个单独的模型：

RegistrationError:
  type: object
  properties:
    code:
      type: string
      enum:
        - USERNAME_VALIDATION_FAILED
        - EMAIL_VALIDATION_FAILED

Error:
  type: object
  properties:
    code:
      type: string
      enum:
        - USERNAME_VALIDATION_FAILED
        - EMAIL_VALIDATION_FAILED
        - USERNAME_EXISTS
        - ...

如果错误模型具有共同的属性，您可以"inherit"它们来自基本模型以减少代码重复：

BaseError:
  type: object
  properties:
    message:
      type: string

RegistrationError:
  allOf:
    - $ref: "#/definitions/BaseError"
    - type: object
      properties:
        code:
          type: string
          enum:
            - USERNAME_VALIDATION_FAILED
            - EMAIL_VALIDATION_FAILED

Error:
  allOf:
    - $ref: "#/definitions/BaseError"
    - type: object
      properties:
        code:
          type: string
          enum:
            - USERNAME_VALIDATION_FAILED
            - EMAIL_VALIDATION_FAILED
            - USERNAME_EXISTS
            - ...

swagger limit 响应的错误代码

swagger limit error codes of response

rest

swagger-ui

swagger-2.0