08.`spring boot`集成`swagger`

1. 核心依赖

1. 依赖

   <!-- swagger -->
   <dependency>
       <groupId>io.springfox</groupId>
       <artifactId>springfox-swagger2</artifactId>
       <version>2.9.2</version>
   </dependency>
   
   <dependency>
       <groupId>io.springfox</groupId>
       <artifactId>springfox-swagger-ui</artifactId>
       <version>2.9.2</version>
   </dependency>
   
   <!-- swagger 主题 -->
   <dependency>
       <groupId>com.github.xiaoymin</groupId>
       <artifactId>swagger-bootstrap-ui</artifactId>
       <version>1.9.6</version>
   </dependency>
   

2. 说明

   • 没有starter
   • swagger-bootstrap-ui是国内的一个开源swagger主题

2. 配置

1. 配置JavaConfig

   @Configuration
   public class SwaggerConfig {
       @Bean
       public Docket docket(ApiInfo apiInfo) {
           return new Docket(DocumentationType.SWAGGER_2)
                   .apiInfo(apiInfo);
       }
   
       @Bean
       public ApiInfo apiInfo() {
           return new ApiInfoBuilder()
                   .title("项目接口文档")
                   .description("项目的所有 api 文档")
                   .version("1.0.0")
                   .build();
       }
   }
   

2. 启动类中添加@EnableSwagger2注解标记

   @SpringBootApplication
   @EnableSwagger2
   public class TestApplication {
       public static void main(String[] args) {
           SpringApplication.run(TestApplication.class, args);
       }
   }
   

3. 常用注解

4. 查看

1. ip:端口/context-path/swagger-ui.html
2. context-path为主配置文件application.yml中设置的值，没有则省略。

5. 栗子

1. 栗子1

   @ApiOperation(value = "查询所有", httpMethod = "GET")
   @ApiImplicitParams({
       @ApiImplicitParam(name = "offset", defaultValue = "0", value = "分页的偏移量"),
       @ApiImplicitParam(name = "limit", defaultValue = "10", value = "每页的条数"),
   })
   @ApiResponses(value = {
       @ApiResponse(code = 400, message = "参数错误"),
       @ApiResponse(code = 404, message = "资源未找到"),
       @ApiResponse(code = 405, message = "协议错误")    
   })
   @GetMapping("/list")
   public TableData<User> list(@RequestParam(defaultValue = "0") Integer offset, @RequestParam(defaultValue = "10") Integer limit) {
       return userService.list(offset, limit);
   }
   

2. 栗子2

   @Api
   @RestController
   @RequestMapping("/login")
   public class LoginController {
       @Resource
       private UserService userService;
   
       @ApiOperation("登录")
       @GetMapping("/login")
       public ResultBean<UserVo> login(@ApiParam(value = "账号/手机号/邮箱", required = true)
                                       @RequestParam String condition,
                                       @ApiParam(value = "密码", required = true)
                                       @RequestParam String password,
                                       @ApiIgnore HttpSession session) {
           UserDto userdto = userService.login(condition, password);
           // 返回参数
           UserVo userVo = new UserVo();
           // 复制值
           BeanUtils.copyProperties(userdto, userVo);
           // 共享用户信息
           session.setAttribute("user", userVo);
           session.setAttribute("userId", userdto.getUserId());
           return ResultBean.success(StatusCodeEnum.SUCCESS, userVo);
       }
   }
   

3. 栗子3

   @Data
   @ApiModel("用户信息")
   public class UserDto implements Serializable {
       @ApiModelProperty(value = "用户id", required = true)
       private Integer userId;
      
       @ApiModelProperty("用户昵称，可用于登录")
       private String userNickname;
       
       @ApiModelProperty("用户真实姓名")
       private String userName;
      
       @ApiModelProperty("用户手机号，可用于登录")
       private String userPhone;
       
       @ApiModelProperty("用户邮箱，可用于登录")
       private String userEmail;
   
       @ApiModelProperty("用户性别，默认为0（保密），1（男），2（女）")
       private Integer userSex;
   
       @ApiModelProperty("用户生日")
       private Date userBirthday;
   
       @ApiModelProperty("用户头像")
       private String userPic;
   }