SpringBoot整合Swagger2
相信各位在公司写API文档数量应该不少，当然如果你还处在自己一个人开发前后台的年代，当我没说，如今项目开发都是前后端分离，无论为了前后台更好的对接，还是为了以后交接方便，都有要求写API文档。
【手写Api文档的几个痛点：】
-
文档需要更新的时候，需要再次发送一份给前端，也就是文档更新交流不及时。
-
不能直接在线测试接口，通常需要使用工具，比如postman
-
接口文档太多，不好管理
Swagger（官网：https://swagger.io/）也就是为了解决这个问题，当然也不能说Swagger就一定是完美的，当然也有缺点，最明显的就是代码移入性比较强。
【springboot整合Swagger】
一：pom依赖
|
1 2 3 4 5 6 7 8 9 10 11 12 |
< 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 > </ dependencies > |
注意：需要指定版本号，因为springboot父工程没有管理swagger的版本号
二、Swagger配置类
其实这个配置类，只要了解具体能配置哪些东西就好了，毕竟这个东西配置一次之后就不用再动了。 特别要注意的是里面配置了api文件也就是controller包的路径，不然生成的文档扫描不到接口。
|
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 |
package com.wendao.swagger.config;
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; @Configuration public class Swagger2Configuration {
@Bean public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()) .select() .apis(RequestHandlerSelectors.basePackage( "com.wendao.swagger.web" )) .paths(PathSelectors.any()) .build(); }
private ApiInfo apiInfo() {
return new ApiInfoBuilder() .title( "问道学院" ) .description( "线上教学平台" ) .termsOfServiceUrl( "http://www.wendaoxueyuan.com" ) .version( "1.0" ) .build(); } } |
注意： 从Spring3.0，@Configuration用于定义配置类，使用java配置替换xml配置文件，等价于XML中配置beans
三：在引导类中开启swagger
四：Restful 接口文档
|
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 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 |
package com.wendao.swagger.web;
import com.wendao.swagger.pojo.Result; import com.wendao.swagger.pojo.User; import io.swagger.annotations.ApiImplicitParam; import io.swagger.annotations.ApiImplicitParams; import io.swagger.annotations.ApiOperation; import org.springframework.web.bind.annotation.*; import springfox.documentation.annotations.ApiIgnore;
import java.util.*;
@RestController public class UserController {
// 创建线程安全的Map static Map<Integer, User> users = Collections.synchronizedMap( new HashMap<Integer, User>());
/** * 添加用户 * * @param user * @return */ @ApiOperation (value = "创建用户" , notes = "根据User对象创建用户" ) @ApiImplicitParam (name = "user" , value = "用户详细实体user" , required = true , dataType = "User" ) @RequestMapping (value = "user" , method = RequestMethod.POST) public Result add( @RequestBody User user) {
return new Result( true , "添加成功" ); }
/** * 根据id删除用户 * * @param id * @return */ @ApiOperation (value = "删除用户" , notes = "根据url的id来指定删除用户" ) @ApiImplicitParam (name = "id" , value = "用户ID" , required = true , dataType = "Long" , paramType = "path" ) @RequestMapping (value = "user/{id}", method = RequestMethod.DELETE) public Result delete( @PathVariable (value = "id" ) Integer id) {
return new Result( true , "删除成功" ); }
/** * 根据id修改用户信息 * * @param user * @return */ @ApiOperation (value = "更新信息" , notes = "根据url的id来指定更新用户信息" ) @ApiImplicitParams ({
@ApiImplicitParam (name = "id" , value = "用户ID" , required = true , dataType = "Long" , paramType = "path" ), @ApiImplicitParam (name = "user" , value = "用户实体user" , required = true , dataType = "User" ) }) @RequestMapping (value = "user/{id}", method = RequestMethod.PUT) public Result update( @PathVariable ( "id" ) Integer id, @RequestBody User user) {
return new Result( true , "修改成功" ); }
/** * 根据ID查询用户 * * @param id * @return */ @ApiOperation (value = "获取用户详细信息" , notes = "从url的id来获取用户详细信息" ) @ApiImplicitParam (name = "id" , value = "用户ID" , required = true , dataType = "Integer" , paramType = "path" ) @RequestMapping (value = "user/{id}", method = RequestMethod.GET) public User getUserById( @PathVariable (value = "id" ) Integer id) {
return new User( "jack" , 12 ); }
/** * 查询用户列表 * * @return */ @ApiOperation (value = "获取用户列表" , notes = "获取用户列表" ) @RequestMapping (value = "users" , method = RequestMethod.GET) public List<User> getUserList() {
List<User> userList = new ArrayList<>(); userList.add( new User( "jack" , 12 )); userList.add( new User( "rose" , 19 )); return userList; }
@ApiIgnore //使用该注解忽略这个API @RequestMapping (value = "/hi" , method = RequestMethod.GET) public String jsonTest() {
return " hi you!" ; }
} |
实体类
|
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 |
package com.wendao.swagger.pojo;
public class User {
private Long id;
private String username; private int age;
public String getUsername() {
return username; }
public void setUsername(String username) {
this .username = username; }
public int getAge() {
return age; }
public void setAge( int age) {
this .age = age; }
public Long getId() {
return id; }
public void setId(Long id) {
this .id = id; }
public User(String username, int age) {
this .username = username; this .age = age; }
public User() {
} } |
页面传递信息类
|
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 |
package com.wendao.swagger.pojo;
import java.io.Serializable;
/** * 用于向页面传递信息的类 * @author jt * */ public class Result implements Serializable{
private boolean flag; private String message; public Result( boolean flag, String message) {
super (); this .flag = flag; this .message = message; } public boolean isFlag() {
return flag; } public void setFlag( boolean flag) {
this .flag = flag; } public String getMessage() {
return message; } public void setMessage(String message) {
this .message = message; } } |
五、查看Swagger2文档
启动SpringBoot项目，访问 http://localhost:8080/swagger-ui.html
六、Swagger注解
swagger通过注解表明该接口会生成文档，包括接口名、请求方法、参数、返回信息的等等。
-
@Api：修饰整个类，描述Controller的作用
-
@ApiOperation：描述一个类的一个方法，或者说一个接口
-
@ApiParam：单个参数描述
-
@ApiModel：用对象来接收参数
-
@ApiProperty：用对象接收参数时，描述对象的一个字段
-
@ApiResponse：HTTP响应其中1个描述
-
@ApiResponses：HTTP响应整体描述
-
@ApiIgnore：使用该注解忽略这个API
-
@ApiError ：发生错误返回的信息
-
@ApiImplicitParam：一个请求参数
-
@ApiImplicitParams：多个请求参数
七：完整代码
https://pan.baidu.com/s/1c4gjtJS1z4_2F0te7q8E6Q
阅读更多
- spring boot整合Swagger2
- SpringBoot实战之12 整合restful工具swagger2
- Spring Boot学习笔记 - 整合Swagger2自动生成RESTful API文档
- SpringBoot整合Swagger2
- spring boot 整合Swagger2
- 个人推荐：SpringBoot整合Swagger2
- SpringBoot整合Swagger2
- spring boot整合Swagger2的示例代码
- SpringBoot之整合Swagger2
- SpringBoot整合系列-整合Swagger2
- Swagger（一） SpringBoot整合Swagger2简单的例子
- SpringBoot（七）：SpringBoot整合Swagger2
- Swagger（一） SpringBoot整合Swagger2简单的例子
- Swagger（一） SpringBoot整合Swagger2简单的例子
- 2018 最新 spring boot 整合 swagger2 (swagger2 版本 2.8.0)
- Spring Boot 整合Spring Security 和Swagger2 遇到的问题小结
- Springboot整合swagger2项目的部署问题
- Spring Boot整合Swagger2的完整步骤详解
- Spring Boot 整合mybatis 与 swagger2
- Spring Boot整合Swagger2