一、前言
随着互联网项目前后端分离方式的流行,前端与后端交给不同的人员开发,项目沟通成本也随之提高。
主要表现在WebAPI接口的沟通,Swagger2 应运而生,它可以动态生成Api接口文档,降低沟通成本,促进项目高效开发。
下面讨论Swagger2及swagger-bootstrap-ui在SpringBoot上的集成
二、SpringBoot项目集成swagger
1. 引入依赖
1
2
3
4
5
6
7
8
9
10
|
< dependency > < groupId >io.springfox</ groupId > < artifactId >springfox-swagger2</ artifactId > < version >2.8.0</ version > </ dependency > < dependency > < groupId >io.springfox</ groupId > < artifactId >springfox-swagger-ui</ artifactId > < version >2.8.0</ version > </ dependency > |
2. 编写配置文件
可对照进行相应的修改
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
|
@Configuration @EnableSwagger2 @EnableSwaggerBootstrapUI @Profile ({ "dev" , "test" }) public class Swagger2Config { @Bean public Docket createRestApi() { return new Docket(DocumentationType.SWAGGER_2) .groupName( "" ) //指定分组,对应(/v2/api-docs?group=) .pathMapping( "" ) //base地址,最终会拼接Controller中的地址 .apiInfo(apiInfo()) .select() //为当前包路径 // .apis(RequestHandlerSelectors.any()) .apis(RequestHandlerSelectors.basePackage( "com.riskeys.sd.custom" )) .paths(PathSelectors.any()) .build(); } //构建 api文档的详细信息函数 private ApiInfo apiInfo() { return new ApiInfoBuilder() //页面标题 .title( "XXX API对接文档" ) .description( "XX API对接文档" ) //描述 //创建人 .contact( new Contact( "yuhei001" , "https://blog.csdn.net/Yuhei0" , "18616591658@163.com" )) //版本号 .version( "1.0" ) //描述 .description( "API 描述" ) .build(); } } |
3. 启动访问页面
http://127.0.0.1:10086/swagger-ui.html
三、SpringBoot项目集成swagger-bootstrap-ui
在步骤二的基础上进行如下操作
1.引入依赖
1
2
3
4
5
|
< dependency > < groupId >com.github.xiaoymin</ groupId > < artifactId >swagger-bootstrap-ui</ artifactId > < version >1.9.6</ version > </ dependency > |
2.配置资源处理规则
未配置的情况下,有可能访问报error.9996。
实现WebMvcConfigurer接口,或者WebMvcConfigurationSupport(老版的SpringBoot),实现addResourceHandlers方法,加上如下所示代码即可。
1
2
3
4
5
6
7
8
9
10
11
12
|
@Configuration public class AppWebConfig extends WebMvcConfigurationSupport{ @Override public void addResourceHandlers(ResourceHandlerRegistry registry) { registry.addResourceHandler( "/swagger-ui.html" ).addResourceLocations( "classpath:/META-INF/resources/" ); // 解决 doc.html 404 报错 registry.addResourceHandler( "/doc.html" ).addResourceLocations( "classpath:/META-INF/resources/" ); registry.addResourceHandler( "/webjars/**" ).addResourceLocations( "classpath:/META-INF/resources/webjars/" ); } } |
或者
1
2
3
4
5
6
7
8
9
10
|
@Configuration public class AppWebConfig extends WebMvcConfigurationSupport{ @Override public void addResourceHandlers(ResourceHandlerRegistry registry) { registry.addResourceHandler( "/swagger-ui.html" ).addResourceLocations( "classpath:/META-INF/resources/" ); // 解决 doc.html 404 报错 registry.addResourceHandler( "doc.html" ).addResourceLocations( "classpath*:/META-INF/resources/" ); registry.addResourceHandler( "/webjars/**" ).addResourceLocations( "classpath*:/META-INF/resources/webjars/" ); } } |
另外,也可以在启动类上进行实现重写
1
2
3
4
5
6
7
8
|
@SpringBootApplication public class XXXApplication implements WebMvcConfigurer{ @Override public void addResourceHandlers(ResourceHandlerRegistry registry) { registry.addResourceHandler( "doc.html" ).addResourceLocations( "classpath*:/META-INF/resources/" ); registry.addResourceHandler( "/webjars/**" ).addResourceLocations( "classpath*:/META-INF/resources/webjars/" ); } } |
3.启动访问页面
访问http://127.0.0.1:10086/doc.html,相较swagger-ui.html来说,此文档更为清爽。
四、Swagger常用注解介绍
swagger通过注解生成接口文档,包括接口名、请求方法、参数、返回信息等等。
1.Swagger2Config中相关swagger注解
1.1 @EnableSwagger2 开启Swagger
作用于配置类或启动类
1.2 @EnableSwaggerBootstrapUI 开启SwaggerBootstrapUi增强功能
作用于配置类或启动类,如果不使用增强功能,可不开启。
2.controller中相关swagger注解
2.1 @Api:修饰整个类,描述Controller的作用
value和tags均为说明,可用tags代替value
1
|
@Api (value = "保险公司列表查询" , tags = { "保险公司列表查询" }) |
2.2 @ApiOperation() 用于方法;表示一个http请求的操作
1
|
@ApiOperation (value = "信息员保存(注册)/更新" , tags = { "信息員保存" }, notes = "messenger desc" ) |
2.3 @ApiParam 用于方法,参数,字段说明;表示对参数的添加元数据(说明或是否必填等)
适用于单个参数
1
|
@ApiParam (name= "sdMessengerInfo" ,value= "参数描述" ,required= true ) |
2.4 请求参数注解,可进行组合
- @ApiImplicitParams 用于方法,包含多个 @ApiImplicitParam
- @ApiImplicitParam 用于方法,表示单独的请求参数
适用于对多个参数进行描述
示例:
1
2
3
4
5
6
|
// 组合使用 @ApiImplicitParams ({ @ApiImplicitParam (name = "id" , value = "参数中文描述" , required = true ) }) // 单独使用 @ApiImplicitParam (paramType= "query" , name= "id" , dataType= "String" , required= true , value= "参数描述" ) |
注意,当同时存在@ApiParam和@ApiImplicitParam时,以@ApiImplicitParam的描述为准。
2.5 @ApiIgnore() 用于类或者方法上,可以不被swagger显示在页面上 ,使用较少。
2.6 响应配置
- @ApiResponses
- @ApiResponse
1
2
3
4
|
// 单独配置 @ApiResponse (code = 400 , message = "Invalid user supplied" ) // 组合使用 @ApiResponses ({ @ApiResponse (code = 400 , message = "Invalid Order" ) }) |
2.7 @ResponseHeader 响应头设置
1
|
@ResponseHeader (name= "head1" ,description= "response head conf" ) |
3.Model中相关swagger注解
3.1 @ApiModel 用于类 ;表示对类进行说明,用于参数用实体类接收。
1
|
@ApiModel (value = "demo" , description = "对象描述" ) |
一般value和desc可以省略不写
3.2 @ApiModelProperty 用于方法,字段; 表示对model属性的说明或者数据操作更改
1
|
@ApiModelProperty (value = "用户id" ,name = "openid2" ,dataType = "String" , required = true , hidden = true ) |
-
value
–字段说明 -
name
–重写属性名字 -
dataType
–重写属性类型 -
required
–是否必填 -
example
–举例说明 -
hidden
–隐藏
一般只对value,required进行标示。
总结
以上,即为SpringBoot集成Swagger、swagger-bootstrap-ui以及Swagger常用注解相关介绍。
仅为个人经验,希望能给大家一个参考,也希望大家多多支持服务器之家。
原文链接:https://blog.csdn.net/Yuhei001/article/details/113861976