Spring Boot集成Swagger2

程序员文章站 2022-07-03 08:42:43

...

Spring Boot集成Swagger2
封面图：八达岭长城，北京，2012年4月。

Swagger2是一个文档快速构建工具，能够通过注解自动生成一个REST风格JSON形式的接口文档，并可以通过如swagger-ui等工具生成HTML网页形式的接口文档。

为了方便开发和测试，本文将展示如何在Spring Boot中集成Swagger2。

本文基于spring-boot-demo项目进行集成，源代码：https://github.com/wu-boy/spring-boot-demo.git，web模块中的rest模块。

添加依赖

Spring Boot集成Swagger2需要两个依赖，一个是swagger2，一个是swagger-ui，后者是Swagger提供的可视化的交互界面。

<dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
        </dependency>

创建Swagger2配置类

@Configuration
@EnableSwagger2
public class Swagger2Config {

    @Bean
    public Docket docket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.any())
                .build();
    }

}

Springfox 提供了一个 Docket 对象，让我们可以灵活的配置 Swagger 的各项属性。@Configuration 是告诉 Spring Boot 需要加载这个配置类，@EnableSwagger2 是启用 Swagger2。

修改控制器参数UserInsertDto

@ApiModel("新增用户参数")
public class UserInsertDto {

    @ApiModelProperty(value = "生日", required = true)
    @NotNull(message = "日期不能为空")
    //@Future(message = "需要一个将来的日期")
    //@Past(message = "需要一个以前的日期")
    @DateTimeFormat(pattern = "yyyy-MM-dd")
    private Date birthday;

    @ApiModelProperty(value = "Double值", required = true)
    @NotNull(message = "Double值不能为空")
    @DecimalMin(value = "0.1", message = "Double值不能小于0.1")
    @DecimalMax(value = "100.00", message = "Double值不能大于100")
    private Double doubleValue;

    @ApiModelProperty(value = "Integer值", required = true)
    @NotNull(message = "Integer值不能为空")
    @Min(value = 1, message = "Integer值最小值为1")
    @Max(value = 100, message = "Integer值最大值为100")
    private Integer integerValue;

    @ApiModelProperty("range值")
    @Range( min = 1, max = 100, message = "range范围为1至100")
    private Integer range;

    @ApiModelProperty(value = "邮箱", required = true)
    @NotBlank(message = "邮箱不能为空")
    @Email(message = "邮箱格式错误")
    @Size(min = 8, max = 64, message = "邮箱长度要求8至64之间")
    private String email;

    // 请自行补充get/set
}

这里给控制器参数加上Swagger2的注解，用到了两个，一个是@ApiModel，给类添加描述信息；一个是@ApiModelProperty，给属性添加描述信息。

修改控制器UserController

@Api(description = "用户")
@RestController
@RequestMapping("users")
public class UserController {

    /**
     * 启动后，浏览器访问http://localhost:8080/users/1
     * @param id
     * @return
     */
    @ApiOperation("根据用户ID获取用户")
    @GetMapping("{id}")
    public UserInsertDto get(@PathVariable int id){
        UserInsertDto user = new UserInsertDto();
        user.setIntegerValue(id);
        user.setBirthday(new Date());
        user.setEmail("aaa@qq.com");
        return user;
    }

    @ApiOperation("保存用户")
    @PostMapping()
    public String insert(@RequestBody @Valid UserInsertDto dto){
        System.out.println(dto.getBirthday());
        System.out.println(dto.getEmail());
        return "success";
    }
}

控制器用到了两个Swagger2的注解，一个是@Api，给控制器添加描述信息；一个是@ApiOperation，给控制器方法添加描述信息。

Swagger页面

启动项目后，浏览器访问http://localhost:8080/swagger-ui.html，即可打开Swagger文档页面，如下图所示
Spring Boot集成Swagger2
点击user-controller，可以展开看到其中的接口，例如保存用户的接口如下图所示

点击Model，可以看到参数的详细描述信息，带有红色*的属性是必填项，如下图所示

点击Try it out后，可以输入数据进行测试。

文档信息配置

Swagger2支持通过创建一个 ApiInfo 对象来配置一些基本信息，包括标题、联系信息、版本号等。

@Configuration
@EnableSwagger2
public class Swagger2Config {

    @Bean
    public Docket docket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.any())
                .build()
                .apiInfo(apiInfo());
    }

    /**
     * 配置文档信息
     * @return
     */
    private ApiInfo apiInfo(){
        return new ApiInfoBuilder()
                .title("Spring Boot集成Swagger2")
                .contact(new Contact("程序兔兔", "https://github.com/wu-boy", "aaa@qq.com"))
                .version("0.1")
                .description("Spring Boot集成Swagger2的demo")
                .build();
    }

}

统一加入认证参数

实际开发中，很多REST服务都是用户登录后才能访问，一般情况下，服务器在用户登录后会返回给用户一个token，然后用户在HTTP请求的header中带着token去访问各种服务。

Swagger提供了相应的解决方案，代码如下

@Configuration
@EnableSwagger2
public class Swagger2Config {

    // 名字可以自定义，改成Authorization也可以
    private static final String TOKEN = "token";

    @Bean
    public Docket docket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.any())
                .build()
                .apiInfo(apiInfo())
                .securitySchemes(securitySchemes())
                .securityContexts(securityContexts());
    }

    /**
     * 配置文档信息
     * @return
     */
    private ApiInfo apiInfo(){
        return new ApiInfoBuilder()
                .title("Spring Boot集成Swagger2")
                .contact(new Contact("程序兔兔", "https://github.com/wu-boy", "aaa@qq.com"))
                .version("0.1")
                .description("Spring Boot集成Swagger2的demo")
                .build();
    }

    private List<ApiKey> securitySchemes() {
        List<ApiKey> result = new ArrayList<>();
        result.add(new ApiKey(TOKEN, TOKEN, "header"));
        return result;
    }

    private List<SecurityContext> securityContexts() {
        List<SecurityContext> result = new ArrayList<>();
        result.add(SecurityContext.builder().securityReferences(defaultAuth()).build());
        return result;
    }

    List<SecurityReference> defaultAuth() {
        List<SecurityReference> result = new ArrayList<>();
        AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];
        authorizationScopes[0] = new AuthorizationScope("global", "accessEverything");
        result.add(new SecurityReference(TOKEN, authorizationScopes));
        return result;
    }

}