08.`spring boot`集成`swagger`-优快云博客

本文详细介绍了如何使用Swagger在Spring Boot项目中生成API文档，包括核心依赖、配置步骤、注解使用及示例代码，帮助开发者快速上手并提高开发效率。

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>

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

2. 配置

配置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();
    }
}

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

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

3. 常用注解

注解	目标	说明
`@Api`	类	标记该类为`swagger`的资源
`@ApiOperation`	方法	标记该方法为一个`http`的请求操作
`@ApiParam`	形参	描述参数
`@ApiImplicitParams`	方法	装多个`@ApiImplicitParam`
`@ApiImplicitParam`	方法	描述方法的形参
`@ApiMOdel`	类	返回对象类中
`@ApiModelProperty`	类成员	描述参数对象的字段
`@ApiResponses`	方法	响应集配置
`@ApiResponse`	方法	响应配置

4. 查看

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

5. 栗子

栗子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

@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

@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;
}