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配置

package top.javazhangwei.webconfig;


import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/***
* 指定API文档页的标题和描述信息等内容。
*/
@Configuration
@EnableSwagger2
public class MySwagger {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("top.javazhangwei.controller"))//这里是controller所处的包名
.paths(PathSelectors.any())
.build();
}
//构建api文档的详细信息函数
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
//页面标题
.title("spring-boot-web-crud项目")
//描述
.description("api查询测试接口")
.termsOfServiceUrl("API terms of service")
//版本号s
.version("1.0")
.build();
}
}

说明：

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

package top.javazhangwei.controller;

import top.javazhangwei.entities.Diary;
import top.javazhangwei.mapper.DiaryMapper;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.apache.catalina.servlet4preview.http.HttpServletRequest;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

import javax.annotation.Resource;
import java.util.List;

@RestController
@Api(description = "测试api")
public class MyController {
@Resource
private DiaryMapper diaryMapper;
//查询文章和用户信息
@ApiOperation("测试关联查询文章和用户信息")
@RequestMapping("/testDiary")
public List<Diary> getAllDiaryAndUsers(HttpServletRequest request){
List<Diary> list =diaryMapper.getAllDiary();
return list;
}
}
@Controller
@Api(description = "登录api")
public class LoginController {
@Resource
private UsersMapper usersMapper;
@ApiOperation("用户登陆")
@ApiImplicitParams({@ApiImplicitParam(name = "username",value = "用户名",required = true,dataType = "String",paramType="query"),
@ApiImplicitParam(name = "password",value = "密码",required = true,dataType = "String",paramType="query")})
@PostMapping(value = "/user/login")
public String postLogin( @RequestParam("username") String username, @RequestParam("password") String password, HttpSession session, HttpServletRequest request) {
Users users =usersMapper.login(username,password);
if(users!=null){
session.setAttribute("user",users);
return "redirect:/main.html";
}else{
request.setAttribute("msg","用户名或密码错误");
return "login";
}
}

//返回登录界面

@RequestMapping("/login")
@ApiOperation("返回登录界面")
public String login(){
return "login";
}

}

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;
}
 
————————————————
原文链接：https://blog.csdn.net/jav_zhangwei/article/details/81236230