SpringBoot-11-Swagger2的使用_java11版本应该使用哪个版本的springfox swagger-优快云博客

本文链接：https://blog.youkuaiyun.com/ThisAaron/article/details/111029650

一、简介

Swagger的目标是为REST APIs定义一个标准的与语言无关的接口，让人和计算机在看不到源码或者看不到文档或者不能通过网络流量监测的情况下发现和理解各种服务的功能。

当服务通过Swagger定义，消费者就能与远程的服务互动通过少量的实现逻辑。类似于低级编程接口。Swagger去掉了调用服务时的很多猜测。

优点

Swagger号称世界上最流行的API框架
RestFul API文档在线自动生成工程=>API文档与API定义同步更新
直接运行，可以在线测试API接口。
支持多种语言

**官网：**https://swagger.io/

使用Swagger需要SpringBox

Swagger2
ui

二、集成SpringBoot

1、集成Swagger

创建SpringBoot项目

导入依赖

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

编写HelloWord!

配置Swagger

@Configuration
@EnableSwagger2
public class SwaggerConfig {
}

测试运行

2、配置Swagger信息

Swagger的bean实例Docket;

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

通过源码查看Swagger

`Docket`类

Docket类中有个有参构造函数

public Docket(DocumentationType documentationType) {
  this.documentationType = documentationType;
}

点进去参数类型DocumentationType类，有三个静态常量可选择

public static final DocumentationType SWAGGER_12 = new DocumentationType("swagger", "1.2");
public static final DocumentationType SWAGGER_2 = new DocumentationType("swagger", "2.0");
public static final DocumentationType SPRING_WEB = new DocumentationType("spring-web", "1.0");

构造好Docket后就可以设置其中的变量了

比如：配置初始信息.apiInfo(apiInfo());

`apiInfo`方法

调用 apiInfo 给 Docket 作参数

调用 apiInfo 必须传 ApiInfo 参数

private ApiInfo apiInfo(){return new ApiInfo()}

ApiInfo类也需要传参 因为没有set方法

 Contact contact = new Contact("Aaron",
                "https://blog.youkuaiyun.com/ThisAaron?spm=1000.2115.3001.5113",
                "15102635012@163.com");
//        默认的配置信息。覆盖
        return new ApiInfo(
                "Aaron is Swagger API文档",
                "无神论者！",
                "v1.0",
                "https://blog.youkuaiyun.com/ThisAaron?spm=1000.2115.3001.5113",
                contact,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList<VendorExtension>());

3、配置扫描接口及开关

扫描接口

.apis(RequestHandlerSelectors.basePackage("com.aaron.controller"))

指定扫描的包 .basePackage("com.aaron.controller")
指定扫描类上的注解 .withClassAnnotation(RestController.class)
指定扫描方法上的注解 .withMethodAnnotation(RequestMapping.class)
默认：扫描所有 .any()
不扫描 : .none()

.select()
.apis(RequestHandlerSelectors.basePackage("com.aaron.controller"))
.paths(PathSelectors.ant("/aaron/**"))
.build();

过滤

paths(PathSelectors.ant("/aaron/**"))

指定过滤的接口 .ant("/aaron/**"))
过滤所有的接口( 默认的 ) .any()
不过滤接口 .none()
用正则过滤接口 .regex()

开关

关掉Sawgger .enable(false)

浏览器不能在浏览器中访问

题：只希望Swagger在生产环境中使用，在发布中不使用。

创建生产环境和正式环境application-dev.properties和application-pro.properties

在默认环境application.properties设置要访问的环境

spring.profiles.active=dev

判断当前环境是否是生产环境 flag = false

public Docket docket(Environment environment){
    Profiles profiles = Profiles.of("dev");
    boolean flag = environment.acceptsProfiles(profiles);
}

把flag注入enable
```
.enable(flag)
```

4、分组和接口注释

分组

.groupName("Aaron")

一个组一个docket配置

多个人和分多个组配置多个docket

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

Model

只要接口返回的是实体类，就会扫描到Swagger的Model中

@GetMapping("/user")
@ApiOperation("用户控制器")
public User user(@ApiParam("用户名") String username){
    return new User();
}

注解

实体类描述注解 @ApiModel("用户实体类")
参数描述注解 @ApiModelProperty("用户名")
类和方法描述的注解 @ApiOperation("用户控制器")
方法的参数注解 @ApiParam("用户名")

总结

可以通过Swagger给一些比较难理解的属性添加注释信息
接口文档实时更新
可以在线测试

Swagger是非常优秀的工具，几乎所有前后端分离的公司都在使用。

【注意】在正式发布的时候，要关闭Swagger,可节省运行的内存。