SpringBoot 学习（七）Swagger

news2024/12/26 11:12:49

7. Swagger

7.1 简介

便于前后端集成联调
RestFul Api 文档在线生成工具 ==> Api 文档与 Api 定义同步更新
直接运行，在线测试 Api 接口

7.2 springboot 集成 swagger

(1) 导入依赖

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

(2) 集成 swagger

@Configuration
@EnableSwagger2 // 开启 swagger2
public class SwaggerConfig {
}

(3) swagger 页面信息

接口：localhost://8080/swagger-ui.html

在这里插入图片描述

(4) 配置 swagger 信息

@Configuration
@EnableSwagger2 // 开启 swagger2
public class SwaggerConfig {

    // 配置 Swagger Docket 的 bean 实例
    @Bean
    public Docket docket() {
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo());
    }

    // 配置 swagger api 信息
    private ApiInfo apiInfo() {
        // 作者信息
        Contact contact = new Contact("why", "https://gitee.com/", "1942953841@qq.com");
        return new ApiInfo("Why Swagger Api Info",
                            "Why so serious!!!",
                            "v1.0",
                            "https://gitee.com/",
                            contact,
                            "Apache 2.0",
                            "http://www.apache.org/licenses/LICENSE-2.0",
                            new ArrayList()
        );
    }
}

(5) 配置 swagger 自定义扫描接口

// 多环境配置，注解方法
@PropertySource(value = "classpath:application.properties")
@Configuration
@EnableSwagger2 // 开启 swagger2
public class SwaggerConfig {

    // 配置 Swagger Docket 的 bean 实例
    @Bean
    public Docket docket(Environment environment) {
        // 多环境配置，java 方法
        // 设置要显示的 swagger 环境
        // Profiles profiles = Profiles.of("dev", "test");
        // 判断是否处在自己设定的环境中
        // boolean flag = environment.acceptsProfiles(profiles);

        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                // enable 是否启用 swagger
                // .enable(flag)
                .select()
                // RequestHandlerSelectors 配置扫描接口的方式
                // basePackage 指定要扫描的包
                // any() 扫描全部
                // none() 不扫描
                // withClassAnnotation 扫描类上的注解，参数是一个类上的反射对象
                // withMethodAnnotation 扫描方法上的注解
                .apis(RequestHandlerSelectors.basePackage("com.why.swagger.controller"))
                // paths 路径过滤
                // .paths(PathSelectors.ant("/why/**"))
                .build();
    }
}

(6) 多文档分组配置

@Bean
public Docket docket1() {
    return new Docket(DocumentationType.SWAGGER_2).groupName("A");
}

@Bean
public Docket docket2() {
    return new Docket(DocumentationType.SWAGGER_2).groupName("B");
}

@Bean
public Docket docket3() {
    return new Docket(DocumentationType.SWAGGER_2).groupName("C");
}

(7) 注解的使用

实体类

/**
 * @ApiModel 用在类上，表示对类进行说明，用于实体类中的参数接收说明。
 */
@ApiModel(value = "com.why.pojo.User", description = "用户类")
@Data
@AllArgsConstructor
@NoArgsConstructor
public class User {

    /**
     * @ApiModelProperty() 用于字段，表示对 model 属性的说明。
     */
    @ApiModelProperty("用户名")
    private String username;

    @ApiModelProperty("密码")
    private String password;
}

接口

/**
 * @Api 用在类上，说明该类的作用。
 * tags：接口说明，可以在页面中显示。
 */
@Api(tags = "Hello 控制器类")
@RestController
public class HelloController {

    @ApiOperation("hello 方法")
    @GetMapping("/hello")
    public String hello() {
        return "hello";
    }

    /**
     * @ApiOperation 用在 Controller 里的方法上，说明方法的作用，每一个接口的定义。
     * value：接口名称
     * notes：详细说明
     */
    @ApiOperation(value = "user 控制器", notes = "获取用户")

    /**
     * @ApiImplicitParams / @ApiImplicitParam 为单独的请求参数进行说明
     * name：参数名，对应方法中单独的参数名称。
     * value：参数中文说明。
     * required：是否必填。
     * paramType：参数类型，取值为 path、query、body、header、form。
     * dataType：参数数据类型。
     * defaultValue：默认值。
     */
    @ApiImplicitParams({
            @ApiImplicitParam(name = "username", value = "用户名", dataType = "string", paramType = "query", required = true, defaultValue = "why"),
            @ApiImplicitParam(name = "password", value = "密码", dataType = "string", paramType = "query", required = true, defaultValue = "123")
    })

    /**
     * @ApiResponse 用于方法上，说明接口响应的一些信息；@ApiResponses 组装了多个 @ApiResponse。
     */
    @ApiResponses({ @ApiResponse(code = 200, message = "OK", response = User.class) })
    
    @PostMapping(value = "/userObj")
    
    /**
     * @ApiParam 用于 Controller 中方法的参数说明。
     * value：参数说明
     * required：是否必填
     */
    public User userObj(@ApiParam(value = "用户名", required = true) String username,
                        @ApiParam(value = "密码", required = true) String password) {
        User user = new User(username, password);
        System.out.println(user);
        return user;
    }

}

(8) 接口测试

swagger2 测试 get 接口不能传递参数，测试 post 接口可以传递参数

即含参接口使用 @PostMapping 和 @RequestMapping
swagger2 测试含参 @GetMapping 会报如下错误：

TypeError: Failed to execute ‘fetch‘ on ‘Window‘: Request with GET/HEAD method cannot have body.
效果
- Get 方法
- Post