如何将API文档移动到单独的类中？

Question

Swagger 提供了一种记录 REST API 的好方法。然而，有一个问题——方法上面的文档文本使代码看起来很丑。

例如我有一个方法：

@RequestMapping(value = "/something", method = RequestMethod.POST)
public void something(@Valid @RequestBody @ApiParam(value = "Something") SomethingQuery query, HttpServletRequest request, HttpServletResponse response) {
    // ...
}

添加一些描述后，它看起来像这样：

@ApiOperation(value = "Do something",
            consumes = "application/json",
            produces = "application/json",
            notes = "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor " +
                    "incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud " +
                    "exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.")
@ApiResponses(value = {@ApiResponse(code = 400, message = "Bad request. " +
        "This response may be sent e.x. when request is malformed or not valid or something.")})
@RequestMapping(value = "/something", method = RequestMethod.POST)
public void something(@Valid @RequestBody @ApiParam(value = "Something") SomethingQuery query, HttpServletRequest request, HttpServletResponse response) {
    // ...
}

有没有办法将其更改为更清晰易读的内容？

也许是这样的：

@ApiOperation(value = Docs.value, consumes = Docs.consumes, produces = Docs.produces, notes = Docs.notes)
@ApiResponses(value = Docs.responses)
@RequestMapping(value = "/something", method = RequestMethod.POST)
public void something(@Valid @RequestBody @ApiParam(value = "Something") SomethingQuery query, HttpServletRequest request, HttpServletResponse response) {
    // ...
}

我尝试这样做，但很难创建ApiResponses 数组，因为这是注释。

最好的办法是在单独的文件中拥有自己的注释，并为每个字段提供正确的值，然后像这样使用它们：

@ApiOperationSomething
@ApiResponsesSomething
@RequestMapping(value = "/something", method = RequestMethod.POST)
public void something(@Valid @RequestBody @ApiParam(value = "Something") SomethingQuery query, HttpServletRequest request, HttpServletResponse response) {
    // ...
}

但我不知道是否可能。

你们中有人在将文档与实际方法分离并使代码更干净方面有一些经验吗？