Swagger2

官网：https://swagger.io/

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：多个请求参数