大家好,又见面啦。
在前一篇文档《JAVA中自定义扩展Swagger的能力,自动生成参数取值含义说明,提升开发效率》中,我们探讨了如何通过自定义注解的方式扩展swagger的能力让Swagger支持自动从指定的枚举类生成接口文档中的字段描述的实现思路。
其实swagger作为一个被广泛使用的在线接口文档辅助工具,上手会用很容易,但想用好却还是需要一定功夫的。所以呢,本篇文档就和大家一起来聊一聊如何用好swagger,让其真正的成为我们项目交付过程中的神兵利器。
更改接口文档总标题与描述
默认的情况下,Swagger的界面整个文档的名称以及描述内容都是通用值,这会让人拿到文档之后比较困惑,无法知晓这是哪个项目哪个系统哪个服务提供的接口,也不知道接口是哪个团队负责,哪位开发人员维护的。
比如下面这样:
为了体现出接口文档的专业性,让人更容易知晓此接口文档所属系统
、对应版本
、维护团队
等信息,我们可以在代码中根据需要自定义相关的内容。
比如:
@Bean
public Docket createRestApi() {
ApiInfo apiInfo = new ApiInfoBuilder()
.title("资源管理系统接口文档")
.description("资源管理模块对外供APP/WEB端调用的接口详细文档描述")
.version("v1.0.0")
.contact(new Contact("架构悟道", "https://juejin.cn/user/1028798616709294","veezean@outlook.com"))
.termsOfServiceUrl("https://juejin.cn/user/1028798616709294")
.license("Apache License")
.licenseUrl("http://xxx")
.build();
return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo).select().build();
}
重新启动并查看界面,可以发现界面上相关内容已经变更为我们自定义的内容了,是不是比改动前显得更加明晰与专业了?
上述swagger中支持自定义的描述性的字段信息,梳理如下:
字段 | 含义描述 |
---|---|
title | 接口文档的文档标题 |
description | 接口文档的详细整体描述 说明 |
ve |