Swagger

Swagger

API框架

• 可以自动生成API文档
• 可直接运行测试API接口
• 官网：https://swagger.io/

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

编写一个测试Controller

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

开启Swagger2

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

}

访问网址：http://localhost:8080/swagger-ui.html ，成功开启

配置

• 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("联系人名字", "http://xxx.xxx.com/联系人访问链接", "联系人邮箱");
        return new ApiInfo(
                "Swagger学习", // 标题
                "学习演示如何配置Swagger", // 描述
                "v1.0", // 版本
                "http://terms.service.url/组织链接", // 组织链接
                contact, // 联系人信息
                "Apach 2.0 许可", // 许可
                "许可链接", // 许可连接
                new ArrayList<>()// 扩展
        );
    }
}

配置扫描接口

在注册Docket的方法中配置扫描接口

// 配置了Swagger的Docket的Bean实例
@Bean
public Docket docket() {
    return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            .select()
            // RequestHandlerSelectors, 配置要扫描接口的方式
            // basePackage: 指定要扫描的包
            // any: 扫描全部
            // none: 都不扫描
            // withClassAnnotation: 对类上有固定某一个注解的类进行扫描
            // withMethodAnnotation: 扫描方法上的注解
            .apis(RequestHandlerSelectors.withClassAnnotation(RestController.class))
            // 过滤什么路径
            .paths(PathSelectors.ant("/lct/**"))
            .build();
}

Swagger开关

• 在注册Docket的方法中配置开关

.enable(false) // 是否启用Swagger, 如为False则不能访问 http://localhost:8080/swagger-ui.html

根据生产环境决定Swagger页面是否可见

修改配置文件

• applicaiton.properties
  • spring.profiles.active = dev
• applicaiton-dev.properties
  • server.port = 8081
• applicaiton-prod.properties
  • server.port = 8082

在注册Docket的方法中配置是否可见

// 配置了Swagger的Docket的Bean实例
@Bean
public Docket docket(Environment environment) {
    // 获取项目环境
    Profiles profiles = Profiles.of("dev");
    boolean flag = environment.acceptsProfiles(profiles);

    return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            // 根据项目环境决定是否启用Swagger
            .enable(flag)
            .select()
                .apis(RequestHandlerSelectors.basePackage("com.lu.controller"))
                // 过滤什么路径
                .paths(PathSelectors.ant("/lct/**"))
                .build();
}

配置API分组

.groupName("lct")

如何配置多个分组？

在SwaggerConfig类中注册新的Docket Bean

• 效果：进入Swagger页面后可以选择右上角spec

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

实体配置

新建一个实体类

• @ApiModel和@ApiModelProperty用于文档注释，与Swagger是否可以识别实体类没关系
• private属性需要添加get/set方法才能显示
• public直接可以显示

@Data
@ApiModel("用户")
public class User {
    @ApiModelProperty("用户名")
    private String username;
    @ApiModelProperty("密码")
    private String password;
}

编写Controller

• 只要有接口返回一个对象
• 那么那个对象就可以被Swagger识别

@RestController
@RequestMapping("/lct")
public class HelloController {
    @GetMapping("/hello")
    public String hello() {
        return "hello";
    }

    @PostMapping("/user")
    public User user() {
        return new User();
    }
}

注解扩展

@ApiOperation("user!!!") // 接口上的注释
@ApiParam("xxx参数说明") // 方法参数的注释

@ApiOperation("I'm Testing Here")
@GetMapping("/test")
public String test(@ApiParam("Will be Return") String username) {
    return "index";
}

不同皮肤

导入依赖即可，任选一个即可

<!-- 访问: http://localhost:8080/swagger-ui.html -->
<dependency>
   <groupId>io.springfox</groupId>
   <artifactId>springfox-swagger-ui</artifactId>
   <version>2.9.2</version>
</dependency>

<!-- 访问: http://localhost:8080/doc.html -->
<dependency>
   <groupId>com.github.xiaoymin</groupId>
   <artifactId>swagger-bootstrap-ui</artifactId>
   <version>1.9.1</version>
</dependency>

<!-- 访问: http://localhost:8080/docs.html -->
<dependency>
   <groupId>com.github.caspar-chen</groupId>
   <artifactId>swagger-ui-layer</artifactId>
   <version>1.1.3</version>
</dependency>

总结

• 为项目增加注释信息

• 接口文档实时更新

• 可以在线测试接口

• 正式发布要关了