Question

我有一个休息api，我想在Swagger中记录。在所有请求中，API都可以使用401响应。

因此，不是为每条路径一次又一次地再次定义401（不是那么干）。我想定义所有路径都可以返回401。

这可能吗？

Answer 1

我认为这不是一个完美的解决方案，但我这样做是为了试图让它干涸。

在root swagger schema中，您可以定义一个responses对象，该对象由Swagger Spec定义：

保存可跨操作使用的响应的对象。这个 property不会为所有操作定义全局响应。

responses:
  400:
    description: Bad Request
    schema:
      $ref: '#/definitions/Error'
  401:
    description: Unauthorized
    schema:
      $ref: '#/definitions/Error'
  403:
    description: Forbidden
    schema:
      $ref: '#/definitions/Error'
  500:
    description: Internal Server Error
    schema:
      $ref: '#/definitions/Error'

definitions:
  Error:
    type: object
    required:
      - message
    properties:
      message:
        type: string
        description: 'The cause of the Error.'

完成后，您可以在路径中引用共享响应。

paths:
  /keys/:
    get:
      summary: 'Get All API Keys the caller has access to view.'
      responses:
        200:
          description: 'Successfully got Keys'
          schema:
            $ref: '#/definitions/ApiKeyResponse'
        400: 
          $ref: '#/responses/400'
        401:
          $ref: '#/responses/401'
        500:
          $ref: '#/responses/500'

至少可以使您了解response描述以及为该响应类型定义的任何模式。我真的希望有一种方法可以将所有常见的错误响应分组，只是引用该组，但我还没有找到任何方法来做到这一点。

Answer 2

据我所知，这是不可能的。您需要使用@ApiResponse注释每个API端点。类级别唯一可用的注释是@Api和@ApiModel。有关详细信息，请参阅此链接 -

http://docs.swagger.io/swagger-core/v1.5.0/apidocs/io/swagger/annotations/ApiModel.html

如何在Swagger中为所有路径添加401响应

2 个答案: