Question

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

E.x。我有一个方法：

@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) {
    // ...
}

我试图这样做，但很难创建一个ApiResponse的数组，因为这是注释。

最好的是在单独的文件中拥有自己的注释，每个字段都有适当的值，然后像这样使用它们：

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

但我不知道是否有可能。

你们是否有一些将文档与实际方法分离并使代码更加干净的经验？

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

0 个答案: