SpringBoot ---- Swagger 2

Swagger2介绍

前后端分离开发模式中，api文档是最好的沟通方式。

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。

1. 及时性 (接口变更后，能够及时准确地通知相关前后端开发人员)
2. 规范性 (并且保证接口的规范性，如接口的地址，请求方式，参数及响应格式和错误信息)
3. 一致性 (接口信息一致，不会出现因开发人员拿到的文档版本不一致，而出现分歧)
4. 可测性 (直接在接口文档上进行测试，以方便理解业务)

SpringBoot 整合 Swagger2

添加依赖

<!--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>

编写配置类

// 假设分模块，则需要与启动类用一样的包名
@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket webApiConfig(){
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("webApi")  // 组名
                .apiInfo(webApiInfo())
                .select()
                .paths(Predicates.not(PathSelectors.regex("/admin/.*")))  // 不包含此路径
                .paths(Predicates.not(PathSelectors.regex("/error.*")))
                .build();
    }
    private ApiInfo webApiInfo(){
        return new ApiInfoBuilder()  // 定义接口页面信息
                .title("网站-课程中心API文档")
                .description("本文档描述了课程中心微服务接口定义")
                .version("1.0")
                .contact(new Contact("Helen", "http://atguigu.com", "55317332@qq.com"))
                .build();
    }
}

分模块相关

<!-- 需要引入 -->
<dependency>
    <groupId>com.xxx</groupId>
    <artifactId>模块名</artifactId>
    <version>0.0.1-SNAPSHOT</version>
</dependency>

// 在模块启动类中添加扫描。需要同包名
@ComponentScan(backPackages = {"com.xxx"})

访问 Localhost:8080/swagger-ui.html 即可

整合 Spring Security

// 配置权限豁免，才能正常访问 localhost:8080/swagger-ui.html
.antMatchers("/swagger-ui.html").permitAll()
.antMatchers("/swagger-resources/**").permitAll()
.antMatchers("/webjars/**").permitAll()
.antMatchers("/v2/api-docs").permitAll()

Swagger2 注解详解

注解	使用位置	参数
@Api	Class	tags=“接口所在类说明”
@ApiOperation	Method	value=“接口说明” notes=“备注"
@ApiImplicitParam(s)	Method	name=“参数名” value=“参数说明” required=“是否必须”
@ApiParam	Params	name=“参数名” vlaue=“参数说明” required=“是否必须”
@ApiResponse(s)	Method	code=“状态码” message=“信息” response=“异常类”
@ApiModel	Class	value=“Model 名” description=“描述”
@ApiModelProperty	Property	value=“说明” name=“覆盖属性名” example=“示例”

// UserController.java
@Api(tags = "用户管理")
@RestController
@RequestMapping("/user")
public class UserController {

    private UserService userService;

    @Autowired
    public UserController(UserService userService) {
        this.userService = userService;
    }

    /**
     * @PathVariable：通过 url 中读取值
     * @RequestBody：通过 json 获得对象
     */
    @ApiOperation(value = "根据 ID 返回用户")
    @ApiResponses({
            @ApiResponse(code = 200, message = "成功"),
            @ApiResponse(code = 400, message = "未知路径")
    })
    @GetMapping("findUser/{id}")
    public List<User> findUserById(
        @ApiParam(name = "id", value = "user ID", required = true)
        @PathVariable String id) {
        return userService.list();
    }
}

// User.java
@ApiModel(value="User对象", description="用户信息表")
public class User implements Serializable {

    private static final long serialVersionUID=1L;

    @ApiModelProperty(value = "用户 ID")
    private String id;

    @ApiModelProperty(value = "用户名")
    private String username;

    @ApiModelProperty(value = "密码")
    private String password;

    @ApiModelProperty(value = "0：女；1：男")
    private Integer sex;

    @ApiModelProperty(value = "手机号")
    private String tel;

    @ApiModelProperty(value = "邮箱")
    private String email;

    @ApiModelProperty(value = "0：超级管理员；1：管理员；2：读者")
    private Integer power;

    @ApiModelProperty(value = "创建时间")
    private Date createTime;

    @ApiModelProperty(value = "更新时间")
    private Date updateTime;

}