Swagger 的基本使用

Swagger

网地址：https://swagger.io/

在项目中使用 Swagger ：

• swagger2
• ui

Spring Boot 集成 Swagger

1. 新建一个 SpringBoot Web 项目

2. 导入相关依赖

   
   <dependency>
       <groupId>io.springfoxgroupId>
       <artifactId>springfox-swagger2artifactId>
       <version>2.9.2version>
   dependency>
   
   <dependency>
       <groupId>io.springfoxgroupId>
       <artifactId>springfox-swagger-uiartifactId>
       <version>2.9.2version>
   dependency>

3. 编写一个 Hello 工程

   @RestController
   public class HelloController {
   
       @RequestMapping("/hello")
       public String Hello() {
           return "hello Swagger!";
       }
   }

4. 配置 Swagger ==> config

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

5. 测试运行：http://localhost:8080/swagger-ui.html

配置 Swagger

Swagger 的 bean 实例 Docket；

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

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

    // 配置 Swagger 信息 ==> apiInfo
    private ApiInfo apiInfo() {

        // 作者信息
        Contact contact = new Contact("观澄", "https://blog.csdn.net/yemuyouhan", "[email protected]");
        return new ApiInfo(
                "观澄的 Swagger API 学习文档",
                "描述信息：生命不息，学习不止",
                "v1.0",
                "https://blog.csdn.net/yemuyouhan",
                contact,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList()
        );
    }
}

Swagger 配置扫描接口

Docket.select()

// 配置 Swagger 的 Docket 的 bean 实例
@Bean
public Docket docket() {
    return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            .select()
            /*
            * RequestHandlerSelectors：配置要扫描接口的方式
            *   basePackage()：指定要扫描的包
            *   any()：扫描全部
            *   none()：都不扫描
            *   withClassAnnotation()：扫描类上的注解，参数是一个注解的反射对象
            *   withMethodAnnotation()：扫描方法上的注解
            * */
            .apis(RequestHandlerSelectors.basePackage("com.cheng.controller"))
            // paths()：过滤什么路径
            .paths(PathSelectors.ant("/cheng/**"))
            .build();
}

配置是否启动 Swagger

// 配置 Swagger 的 Docket 的 bean 实例
@Bean
public Docket docket() {
    return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            // enable：是否启用 Swagger
            //   true：默认启用
            //   false：不启用
            .enable(false)
            .select()
            .apis(RequestHandlerSelectors.basePackage("com.cheng.controller"))
            // paths()：过滤什么路径
            .paths(PathSelectors.ant("/cheng/**"))
            .build();
}

实际问题解决：只希望 Swagger 在生产环境中使用，在发布的时候不使用

• 判断是不是生产环境 flag = false
• 注入 enable(flag)

注：此处使用的 dev 端口是 8081

application-dev.properties

server.port=8081

配置

// 配置 Swagger 的 Docket 的 bean 实例
@Bean
public Docket docket(Environment environment) {

    // 设置要显示的 Swagger 环境
    Profiles profiles = Profiles.of("dev", "test");
    // 通过 environment.acceptsProfiles 判断是否处在自己设定的环境当中
    boolean flag = environment.acceptsProfiles(profiles);
    System.out.println(flag);

    return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            // enable：是否启用 Swagger
            //   true：默认启用
            //   false：不启用
            .enable(flag)
            .select()
            .apis(RequestHandlerSelectors.basePackage("com.cheng.controller"))
            // paths()：过滤什么路径
            .paths(PathSelectors.ant("/cheng/**"))
            .build();
}

设置 dev 环境

application.properties

spring.profiles.active=dev

测试：

​ 注意测试的时候需要将地址中的端口改为 8081：http://localhost:8081/swagger-ui.html

配置 API 文档的分组

.groupName("分组")

如何配置多个分组？

多个 Docket 实例即可！

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

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

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

实体类配置

实体类

@ApiModel("用户实体类")
public class User {

    @ApiModelProperty("用户名")
    public String username;
    @ApiModelProperty("用户密码")
    public String password;

}

controller

@RestController
public class HelloController {

    @GetMapping("/hello")
    public String Hello() {
        return "hello Swagger!";
    }

    // 只要接口中返回值存在实体类，就会被扫描到 Swagger 中
    @PostMapping("/user")
    public User user() {
        return new User();
    }

    @ApiOperation("hello2 控制类")
    @GetMapping("/hello2")
    public String hello2(@ApiParam("用户名") String username) {
        return "hello" + username;
    }

}

总结：

1. 我们可以通过 Swagger 给一些比较难理解的属性或者接口，增加注释信息
2. 接口文档实时更新
3. 可以在线测试

注意点：在正式发布的时候，关闭 Swagger！！！