SpringBoot整合Swagger自动生成API文档

SpringBoot整合Swagger自动生成API文档

java_zhangwei 2018-07-27 14:38:54 1395 已收藏 3
展开
目录

1.引入Swagger依赖（我这里使用的2.2.2版本，尽可能别使用新版本，不稳定）

2.编写Swagger配置

 

3.编写Controller

4.一切准备就绪，如今打开网页试试

5.相关的注解解释

6.在此过程当中出现的一些问题：

Swagger是一款RESTFUL接口的文档在线自动生成+功能测试功能软件，相比于传统的postman插件，其优势在于：

先后端能够分离开发
API文档很是明确
测试的时候不须要输入url连接
SpringBoot与Swagger结合很是简单
 

1.引入Swagger依赖（我这里使用的2.2.2版本，尽可能别使用新版本，不稳定）

<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.2.2</version>
<scope>compile</scope>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.2.2</version>
<scope>compile</scope>
</dependency>

 

2.编写Swagger配置

 1 package top.javazhangwei.webconfig;
 2 
 3 
 4 import org.springframework.context.annotation.Bean;
 5 import org.springframework.context.annotation.Configuration;
 6 import springfox.documentation.builders.ApiInfoBuilder;
 7 import springfox.documentation.builders.PathSelectors;
 8 import springfox.documentation.builders.RequestHandlerSelectors;
 9 import springfox.documentation.service.ApiInfo;
10 import springfox.documentation.spi.DocumentationType;
11 import springfox.documentation.spring.web.plugins.Docket;
12 import springfox.documentation.swagger2.annotations.EnableSwagger2;
13 
14 /***
15 * 指定API文档页的标题和描述信息等内容。
16 */
17 @Configuration
18 @EnableSwagger2
19 public class MySwagger {
20 @Bean
21 public Docket createRestApi() {
22 return new Docket(DocumentationType.SWAGGER_2)
23 .apiInfo(apiInfo())
24 .select()
25 .apis(RequestHandlerSelectors.basePackage("top.javazhangwei.controller"))//这里是controller所处的包名
26 .paths(PathSelectors.any())
27 .build();
28 }
29 //构建api文档的详细信息函数
30 private ApiInfo apiInfo() {
31 return new ApiInfoBuilder()
32 //页面标题
33 .title("spring-boot-web-crud项目")
34 //描述
35 .description("api查询测试接口")
36 .termsOfServiceUrl("API terms of service")
37 //版本号s
38 .version("1.0")
39 .build();
40 }
41 }

View Code

 

说明：

在这里特别注意下：apis(RequestHandlerSelectors.basePackage("com.yto.controller"))，这个是你Controller所在的包名
配置完后，打开http://127.0.0.1:8080/swagger-ui.html#/看是否能访问不
 
3.编写Controller

 1 package top.javazhangwei.controller;
 2 
 3 import top.javazhangwei.entities.Diary;
 4 import top.javazhangwei.mapper.DiaryMapper;
 5 import io.swagger.annotations.Api;
 6 import io.swagger.annotations.ApiOperation;
 7 import org.apache.catalina.servlet4preview.http.HttpServletRequest;
 8 import org.springframework.web.bind.annotation.RequestMapping;
 9 import org.springframework.web.bind.annotation.RestController;
10 
11 import javax.annotation.Resource;
12 import java.util.List;
13 
14 @RestController
15 @Api(description = "测试api")
16 public class MyController {
17 @Resource
18 private DiaryMapper diaryMapper;
19 //查询文章和用户信息
20 @ApiOperation("测试关联查询文章和用户信息")
21 @RequestMapping("/testDiary")
22 public List<Diary> getAllDiaryAndUsers(HttpServletRequest request){
23 List<Diary> list =diaryMapper.getAllDiary();
24 return list;
25 }
26 }
27 @Controller
28 @Api(description = "登陆api")
29 public class LoginController {
30 @Resource
31 private UsersMapper usersMapper;
32 @ApiOperation("用户登录")
33 @ApiImplicitParams({@ApiImplicitParam(name = "username",value = "用户名",required = true,dataType = "String",paramType="query"),
34 @ApiImplicitParam(name = "password",value = "密码",required = true,dataType = "String",paramType="query")})
35 @PostMapping(value = "/user/login")
36 public String postLogin( @RequestParam("username") String username, @RequestParam("password") String password, HttpSession session, HttpServletRequest request) {
37 Users users =usersMapper.login(username,password);
38 if(users!=null){
39 session.setAttribute("user",users);
40 return "redirect:/main.html";
41 }else{
42 request.setAttribute("msg","用户名或密码错误");
43 return "login";
44 }
45 }
46 
47 //返回登陆界面
48 
49 @RequestMapping("/login")
50 @ApiOperation("返回登陆界面")
51 public String login(){
52 return "login";
53 }
54 
55 }

View Code

 

4.一切准备就绪，如今打开网页试试
若是访问不了页面或者页面的数据没改过来，尝试清除一下浏览器缓存~

 

 

 

5.相关的注解解释

其余注解查看官方文档源码： 
https://github.com/swagger-api/swagger-core/wiki/Annotations#apimodel

6.在此过程当中出现的一些问题：
       1.出现这种提示：

 

 

 

    颇有多是没在Swagger配置上添加自动配置注解：@EnableSwagger2

    或者就是没有扫到controller，检查检查swagger配置上的包名是否正确

 

     2.出现failed to parse JSON/YAML response的问题

       这个缘由就是拦截器把swagger请求拦截了，因此没有接口信息，只须要加个判断容许swagger容许访问便可。

String url=httpServletRequest.getRequestURI();

if(url.indexOf("swagger")!=-1||url.indexOf("api-docs")!=-1){
return true;
}
 
————————————————
原文连接：http://www.javashuo.com/article/p-kuxvaeiv-bz.html