在上一篇整合springdoc-openapi-ui（上）中，我简单介绍了如何使用springdoc-openapi这个库来生成swagger3的api文档，而在这篇下中，我会再补充说明一下其他的一些用法来使你的api文档更加完整可读。
- 参数注解@Parameters
上篇中介绍了用@ApiResponses的注解来生成返回格式，也可以用@ExampleObject来自定义想要的返回内容格式。这里我再举例说明一下@Parameters这个给参数加的注解。例如给SubjectController中的findSubjects加上如下注解
@Parameters({
@Parameter(name = "name", description = "科目名称", schema = @Schema(implementation = String.class), in = ParameterIn.QUERY,
allowEmptyValue = true),
@Parameter(name = "index", description = "页码，从0开始", schema = @Schema(implementation = Integer.class), in = ParameterIn.QUERY),
@Parameter(name = "size", description = "每页条数", schema = @Schema(implementation = Integer.class), in = ParameterIn.QUERY)
})
@GetMapping(value = "/subjects")
public ResponseData findSubjects(final String name, final Integer index, final Integer size){
Page<Subject> page = PageHelper.startPage(index + 1, size);
List<Subject> subjectList = subjectMapper.findSubjects(name);
ResponseData responseData = ResponseData.ok();
responseData.putDataValue("pageCount", page.getPages());
responseData.putDataValue("total", page.getTotal());
responseData.putDataValue("subjects", subjectList);
return responseData;
}
可以得到如下图的结果
api参数说明
其中科目名称name的参数我们给它加上了allowEmptyValue = true，因为默认的参数是不能为空的，而这里作为搜索的关键字参数，它是可以为空的，所以必须要加上这个。
- 格式化返回值
在上篇中我们看到，我们原本使用的ResponseData只定义了3个默认参数，其中data也只是用HashMap定义的通用的返回类型，所以生成的返回值的格式也是比较简单，不能满足文档的阅读需求。上篇中我们采用的方式是自己用字符串拼接出了想要的example格式。
但是其实只要我们明确定义好每个返回的实体类，并加上适当的example注解，也是可以直接生成想要的返回值格式的。
还是以1中的findSubjects为例，我们想要的原本最外层的code和message的参数不变，而data部分，需要固定的返回pageCount、total和一个list。
(1) 首先我们定义一个data部分的entity，叫ListWithPageData，这是专门用来给带分页的列表使用的。
public class ListWithPageData<T> {
@Schema(example = "1")
private int pageCount;
@Schema(example = "8")
private long total;
private List<T> list;
public int getPageCount() {
return pageCount;
}
public long getTotal() {
return total;
}
public List<T> getList() {
return list;
}
public void setPageCount(int pageCount) {
this.pageCount = pageCount;
}
public void setTotal(long total) {
this.total = total;
}
public void setList(List<T> list) {
this.list = list;
}
}
(2) 接着构建一个外层的新的返回实体类叫ResponseDataNew
public class ResponseDataNew<T> {
@Schema(example = "OK")
private String message;
@Schema(example = "200")
private int code;
private T data;
public ResponseDataNew() {
}
public void ok() {
setCode(200);
setMessage("OK");
}
public void setMessage(String message) {
this.message = message;
}
public void setCode(int code) {
this.code = code;
}
public void setData(T data) {
this.data = data;
}
}
(3) 然后就改写了一下findSubjects的方法，让它用ResponseDataNew来返回。
@Parameters({
@Parameter(name = "name", description = "科目名称", schema = @Schema(implementation = String.class), in = ParameterIn.QUERY,
allowEmptyValue = true),
@Parameter(name = "index", description = "页码，从0开始", schema = @Schema(implementation = Integer.class), in = ParameterIn.QUERY),
@Parameter(name = "size", description = "每页条数", schema = @Schema(implementation = Integer.class), in = ParameterIn.QUERY)
})
@GetMapping(value = "/subjects")
public ResponseDataNew<ListWithPageData<Subject>> findSubjects(final String name, final Integer index, final Integer size){
Page<Subject> page = PageHelper.startPage(index + 1, size);
List<Subject> subjectList = subjectMapper.findSubjects(name);
ResponseDataNew<ListWithPageData<Subject>> response = new ResponseDataNew<>();
response.ok();
ListWithPageData<Subject> data = new ListWithPageData<>();
data.setPageCount(page.getPages());
data.setTotal(page.getTotal());
data.setList(subjectList);
response.setData(data);
return response;
}
(4) 最后，因为上一步我们已经在ListWithPageData用具体的entity返回，这里是Subject，所以再给Subject中参数加上example，就可以在api文档中显示出来了。
@Schema(example = "1")
private Long id;
@Schema(example = "语文")
private String name;
我们看一下结果
格式化后的返回值
已经变成了我们需要显示的格式。
当然springdoc-openapi作为生成api文档的第三方库，一定还有很多其他的用法来丰富api文档的内容，我这里也仅仅只是简单介绍了一些常见的用法。其他更多的用法就等待大家一起来发掘，欢迎提出来讨论和交流。
代码依旧可以参考我在github上面的代码https://github.com/ahuadoreen/studentmanager。
