springboot整合Swagger
一:pom依赖
1 2 3 4 5 6 7 8 9 10 11 | <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> |
注意:需要指定版本号,因为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
配置类只需要加上@Configuration这个注解就好了
三:在引导类中开启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!"; }
} |
五、查看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:多个请求参数