Springboot入门教程（8）-整合springdoc-openapi-ui（下）

在上一篇整合springdoc-openapi-ui（上）中，我简单介绍了如何使用springdoc-openapi这个库来生成swagger3的api文档，而在这篇下中，我会再补充说明一下其他的一些用法来使你的api文档更加完整可读。

1. 参数注解@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 page = PageHelper.startPage(index + 1, size);
        List 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，因为默认的参数是不能为空的，而这里作为搜索的关键字参数，它是可以为空的，所以必须要加上这个。

2. 格式化返回值
   在上篇中我们看到，我们原本使用的ResponseData只定义了3个默认参数，其中data也只是用HashMap定义的通用的返回类型，所以生成的返回值的格式也是比较简单，不能满足文档的阅读需求。上篇中我们采用的方式是自己用字符串拼接出了想要的example格式。
   但是其实只要我们明确定义好每个返回的实体类，并加上适当的example注解，也是可以直接生成想要的返回值格式的。
   还是以1中的findSubjects为例，我们想要的原本最外层的code和message的参数不变，而data部分，需要固定的返回pageCount、total和一个list。
   (1) 首先我们定义一个data部分的entity，叫ListWithPageData，这是专门用来给带分页的列表使用的。

public class ListWithPageData {
    @Schema(example = "1")
    private int pageCount;
    @Schema(example = "8")
    private long total;
    private List list;

    public int getPageCount() {
        return pageCount;
    }

    public long getTotal() {
        return total;
    }

    public List getList() {
        return list;
    }

    public void setPageCount(int pageCount) {
        this.pageCount = pageCount;
    }

    public void setTotal(long total) {
        this.total = total;
    }

    public void setList(List list) {
        this.list = list;
    }
}

(2) 接着构建一个外层的新的返回实体类叫ResponseDataNew

public class ResponseDataNew {
    @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> findSubjects(final String name, final Integer index, final Integer size){
        Page page = PageHelper.startPage(index + 1, size);
        List subjectList = subjectMapper.findSubjects(name);
        ResponseDataNew> response = new ResponseDataNew<>();
        response.ok();
        ListWithPageData 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。