SpringMVC整合SpringFox实践总结

项目中使用的swagger框架在生成api文档时存在一些问题:
1、 控制器下方法无法点击展开
2、api内容结构混乱

基于上述原因，重新整合重构了一下api文档生成的代码。在此将重整过程记录下来，方便后续查看。

Maven依赖引入
要整合SpringFox所需的依赖如下：

<!--springfox-swagger需要的最小依赖 start-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.6.1</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.6.1</version>
</dependency>

<!--jackson用于将springfox返回的文档对象转换成JSON字符串-->
<dependency>
<groupId>com.fasterxml.jackson.core</groupId>
<artifactId>jackson-annotations</artifactId>
<version>${version.jackson}</version>
</dependency>
<dependency>
<groupId>com.fasterxml.jackson.core</groupId>
<artifactId>jackson-databind</artifactId>
<version>${version.jackson}</version>
</dependency>
<dependency>
<groupId>com.fasterxml.jackson.core</groupId>
<artifactId>jackson-core</artifactId>
<version>${version.jackson}</version>
</dependency>

<!--petStore是官方提供的一个代码参考, 可用于后期写文档时进行参考, 可不加-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-petstore</artifactId>
<version>2.5.0</version>
</dependency>
<!--最小依赖 end-->
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
36
由于项目框架版本限制，此处只使用2.6版本的SpringFox。另外，根据项目实际情况解决依赖冲突。

添加swagger配置类
import org.springframework.context.annotation.Bean;
import org.springframework.web.servlet.config.annotation.EnableWebMvc;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Tag;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger.web.UiConfiguration;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
* @author yanzy
* @description api文档配置类
* @date 2018-03-27 14:55
* @created by intelliJ IDEA
*/
@EnableWebMvc
@EnableSwagger2
public class SwaggerConfig{
@Bean
public Docket api() {

return new Docket(DocumentationType.SWAGGER_2)
.groupName("api") // 组名
.tags(new Tag("SMR-Services","xxx控制器"),
new Tag("Shiro-Services","xxx控制器"))
.select() // 选择哪些路径和api会生成document
.apis(RequestHandlerSelectors.basePackage("packageName"))//// 对packageName包中的api进行监控
.paths(PathSelectors.any()) // regex, ant, any (default), none 格式：PathSelectors.any()
.build()
.apiInfo(apiInfo());
}

private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("SDD api navigation")//You application title. Required.
.description("API Document")//API description. Arbitrary text in CommonMark or HTML.
.version("1.0.0")//API version. You can use semantic versioning like 1.0.0, or an arbitrary string like 0.99-beta. Required.
.termsOfServiceUrl("no terms of service")//Link to the page that describes the terms of service.Must be in the URL format.
.license("Apache 2.0")//Name of the license.
//.contact(new Contact("yanzy","","yanzy@dist.com.cn"))//Contact information: name, email, URL.
.licenseUrl("http://www.apache.org/licenses/LICENSE-2.0.html")//A URL to the license description.
.build();
}

@Bean
UiConfiguration uiConfiguration() {
UiConfiguration uiConfiguration = new UiConfiguration(null);
return uiConfiguration;
}
}
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
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
此处特别注意tags的使用，上述问题2中无法点击展开控制器下方法就是由于在控制器的@Api标签中使用tags参数导致的。

SpringMVC的XML配置文件相关配置
<!-- Swagger config配置类的路径，注意放在此处，否则生成不了api doc -->
<bean class="dist.dgp.configs.SwaggerConfig"/>
<!--下面两个是静态资源访问配置-->
<mvc:resources location="classpath:/META-INF/resources/" mapping="swagger-ui.html"/>
1
2
3
4
具体使用用例
import dist.dgp.bll.impls.smr.SMRMaterialServiceImpl;
import dist.dgp.model.smr.pos.MaterialPo;
import io.swagger.annotations.*;
import lombok.Data;
import lombok.extern.slf4j.Slf4j;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RestController;

/**
* @author yanzy
* @description
* @date 2018-04-11 14:42
* @created by intelliJ IDEA
*/
@RestController
@RequestMapping("materialController")
@Api
@Data
@Slf4j
public class MaterialService {
@Autowired
SMRMaterialServiceImpl smrMaterialService;

@RequestMapping(value = "/create",method = {RequestMethod.POST})
@ApiOperation(tags = {"SMR-Services"},value = "Material-新建")
@ApiImplicitParams({
@ApiImplicitParam(name = "materialPo", value = "资料报告对象", required = true, paramType = "RequestBody", dataType = "MaterialPo")
})
@ApiResponses({
@ApiResponse(code = 200,message = "OK",response = boolean.class),
@ApiResponse(code = 400,message = "FAULT",response = boolean.class)
})
public boolean create(@RequestBody MaterialPo materialPo){
return this.smrMaterialService.createMaterial(materialPo);
}

@RequestMapping(value = "/saveorupdate",method = {RequestMethod.POST})
@ApiOperation(tags = {"SMR-Services"},value = "Material-保存或更新",notes = "根据\"id\"是否已存在来判断是保存还是更新")
@ApiImplicitParams({
@ApiImplicitParam(name = "materialPo", value = "资料报告对象", required = true, paramType = "body", dataType = "MaterialPo")
})
public boolean saveorupdate(@RequestBody MaterialPo materialPo){
return this.smrMaterialService.saveOrUpdateMaterial(materialPo);
}
}
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
36
37
38
39
40
41
42
43
44
45
46
47
48
最终显示结果为：

按照上述过程操作完，你就能得到一个swagger api document了，访问地址如下:
[ip]:[port]/../swagger-ui.html
本篇内容为对springfox的基本使用，细节将在日后慢慢补充。
---------------------
版权声明：本文为CSDN博主「焱魔王」的原创文章，遵循CC 4.0 by-sa版权协议，转载请附上原文出处链接及本声明。
原文链接：https://blog.csdn.net/yzy199391/article/details/79913011