springBoot集成swagger2在线生成API接口
场景
相信很多后端开发最烦的就是写文档，感觉文档比代码难写的有没有？在遇到前端小姐姐/测试小姐姐要接口文档的时候是不是特别难受香菇。今天就来说说解救广大后端人员的福音。
一，Swagger2集成jar引入（我们用maven管理jar）
pom增加：
二，增加配置（我目前的项目是springBoot）
@Configuration
@EnableSwagger2
public class SwaggerConfig extends WebMvcConfigurer {
@Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {
registry.addResourceHandler("swagger-ui.html")
.addResourceLocations("classpath:/META-INF/resources/"); //注册静态资源目录
registry.addResourceHandler("/webjars/**") //一定注意路径是/webjars/**
.addResourceLocations("classpath:/META-INF/resources/webjars/");
}
//可以注入多个doket，也就是多个版本的api，可以在看到有三个版本groupName不能是重复的，v1和v2是ant风格匹配，配置文件
@Bean
public Docket api() {
//可以添加多个header或参数
ParameterBuilder aParameterBuilder = new ParameterBuilder();
aParameterBuilder
.parameterType("header") //参数类型支持header, cookie, body, query etc
.name("token") //参数名
.defaultValue("token") //默认值
.description("header中token字段测试")
.modelRef(new ModelRef("string"))//指定参数值的类型
.required(false).build(); //非必需，这里是全局配置，然而在登陆的时候是不用验证的
List
aParameters.add(aParameterBuilder.build());
return new Docket(DocumentationType.SWAGGER_2)
.groupName("v1")
.select()
.apis(RequestHandlerSelectors.any()) //设置包过滤
.paths(PathSelectors.any()) //设置方法requestMapping过滤
.build()
.apiInfo(apiInfo1())
.globalOperationParameters(aParameters); //设置是否需要token验证
}
private ApiInfo apiInfo1() {
return new ApiInfoBuilder()
.title("手机运营端Api 0.01")
.termsOfServiceUrl("www.example.com")
.contact(new Contact("zhengwen","https://blog.csdn.net/zwrlj527","[email protected]"))
.version("v0.01")
.build();
}
}
WebMvcConfigurer 注意最好是用这个，WebMvcConfigurerAdapter这个目前已过时，看我用的jar版本就知道，我不喜欢用旧的。WebMvcConfigurationSupport用这个容易后面容易出现No mapping for GET /webjars/的问题，哪怕你注册了静态文件映射。
@EnableSwagger2这个注解别忘记了哦，这个意思是开启Swagger2
其他基本每一行都有注释，注意RequestHandlerSelectors和PathSelectors，之前就呗这里坑了，这里一个是设置包扫描范围，一个是设置方法名范围
三，接口相关的修改
controller的注解标签首先是使用@RestController，目前前后端分离估计都是用的这个了。
然后加上@Api(value = "租户合同API")
方法上增加：
@ApiOperation(value="获取合同列表", notes="获取合同列表")
@ApiImplicitParams({
@ApiImplicitParam(name = "userId", value = "用户ID", required = true, dataType = "String",paramType = "path"),
@ApiImplicitParam(name = "companyId", value = "项目ID", required = true, dataType = "String",paramType = "path"),
@ApiImplicitParam(name = "status", value = "合同状态", required = true, dataType = "String",paramType = "path"),
@ApiImplicitParam(name = "page", value = "页码", required = false, dataType = "int",paramType = "RequestParam"),
@ApiImplicitParam(name = "size", value = "每页显示数量", required = false, dataType = "int",paramType = "RequestParam")
})
@GetMapping("/getSubscribeList/{userId}/{companyId}/{status}")
public Result getSubscribeList(@PathVariable String userId,@PathVariable String companyId,@PathVariable String status,@RequestParam(defaultValue = "0") Integer page, @RequestParam(defaultValue = "0") Integer size) {
//TODO your business code
}
@ApiOperation作用是后面可以在页面上看到方法的描述
@ApiImplicitParams作用也是介绍接口入参的，
@ApiImplicitParam单个参数的描述，
注意里面的name值要与参数对应，value是描述，到时候入参表单上的输入框会显示对应的描述。required这个就是是否必传，应该不需要解释，dataType数据类型，注意这里好像有的包装类型没有，比如int的Integer，如果写这个后面在页面做尝试调用的时候有警告。paramType这个里面感觉就是随便写了，也就是描述参数类型，比如我这里写path意思是在路径上，写RequestParam表示是在?后面。
四，启动springboot增加注解
同样的也是在springboot的application类上增加@EnableSwagger2
五，启动看效果
看到没，这里就是所有api接口的controller了，每一个方法是get/post等都写的清清楚楚，需要在线调用的话，就点try it out，然后输入没个参数，点击执行
然后下面就可以看到出参response
六，常见问题
1.No handler found for GET /swagger-ui.html
看看你是否放开了这个方法的校验，如果你开了spring的secreity，那需要关闭或排除（后面先调用一次登录接口，再试其他的应该是可以的）。我这里使用的不是这个，也类似，可以设置放开方法。基本上需要放开的会有下面这些
/swagger-ui.html/**,/webjars/**,/swagger-resources/**
2，No operations defined in spec!
这个基本就是RequestHandlerSelectors和PathSelectors的坑，没有设置包范围跟方法范围
七，补充
实际上这个在实体类上也是有对应注解标签的，这样测试都不用来问你每个字段的意思。我这里没有加注释，但是字段，字段类型都已经有了。就差中文注释了
补充几个效果图
八，用后感说明
首先不得不承认这个确实很牛逼，但是编码过程中有侵入，需要开发写一写额外的注解，当然如果不写，用也是可以的，但是没有解释字段意思用不好走火入魔的。
然后这个搞完基本前端可以直接对接。文档应该也可以生成的。
另外想到的一个场景就是之前我们这边的售前希望有一些接口可以界面话让他们演示效果，比如设备的控制。用这个就非常棒了，都不用再开发页面了。