如何在Java jersey Swagger UI中添加自定义ApiResponse

Question

我正在使用Swagger UI框架来记录API。我有的API之一是

@GET
@Path("/books/count")
@Produces(MediaType.APPLICATION_JSON)
@ApiOperation(value = "Get total book count in system")
@ApiResponses(value=@ApiResponse(code = 200, message = "Successful operation", response=**need custom response here**))
public Response getBookCount(){
int count = bookService.getCount();
JSONObject jsonObj = new JSONObject();
jsonObj.put("Count", count);

return Response.status(Status.OK).entity(jsonObj.toString()).build();
}

上面的API返回一个具有“count”字段的Json对象。那么，有没有可能有一个大摇大摆的用户界面响应，类似于-

@apiResponses(value=@apiResponse（代码=200，message=“成功操作”，response={“count”：“int”}））

Answer 1

您可以通过使用泛型类型或对象来做到这一点。对我来说，对象更有意义。

请尝试使用下面的swagger.yml，由此生成的代码将是泛型类型。

openapi: 3.0.1
info:
  title: Swagger Bookstore
  description: 'This is a sample server Bookstore server.'
  version: 1.0.0
servers:
- url: http://bookstore.swagger.io/v2
tags:
- name: book
  description: Everything about your Books
paths:
  /books/count:
    get:
      tags:
      - book
      summary: Get Books count
      description: Fetch total book count
      operationId: getBookCount
      responses:
        200:
          description: successful operation
          content:
            application/json:
              schema:
               $ref: '#/components/schemas/ApiResponse'
        400:
          description: Invalid response
          content: {}
components:
  schemas:
    ApiResponse:
      type: object
      properties:
        code:
          type: integer
          format: int32
        message:
          type: string
        response: 
          type: object

您可以看到ApiResponse有一个字段名response作为对象是泛型类型。哪个可以保存您指定的任何类型？

response: 
   type: object

@ApiResponses(value=@ApiResponse(code = 200, message = "Successful operation", response={}))