SpringBoot中集成Swagger-阿里云开发者社区

一、集成Swagger2

1. pom引用

<properties><java.version>1.8</java.version><swagger.version>2.9.2</swagger.version><fastjson.version>1.2.75</fastjson.version><hutool.version>5.7.16</hutool.version></properties><dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-web</artifactId></dependency><dependency><groupId>org.hibernate.validator</groupId><artifactId>hibernate-validator</artifactId></dependency><dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger2</artifactId><version>${swagger.version}</version></dependency><dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger-ui</artifactId><version>${swagger.version}</version></dependency><dependency><groupId>com.alibaba</groupId><artifactId>fastjson</artifactId><version>${fastjson.version}</version></dependency><dependency><groupId>cn.hutool</groupId><artifactId>hutool-all</artifactId><version>${hutool.version}</version></dependency><dependency><groupId>org.projectlombok</groupId><artifactId>lombok</artifactId><optional>true</optional></dependency>

说明：

项目中使用了Validated，即hibernate-validator
swagger使用了2.9.2版本

springfox-swagger2
springfox-swagger-ui

fastjson不再赘述
hutool-all java工具类库https://www.hutool.cn/
lombok在编译期生成get、set、toString等等，减少构建代码

2. Swagger2配置类

packagecom.example.config;
importorg.springframework.context.annotation.Configuration;
importspringfox.documentation.swagger2.annotations.EnableSwagger2;
@Configuration@EnableSwagger2publicclassSwaggerConfig {
}

3. 访问Swagger2页面

访问地址：http://localhost:9090/swagger-ui.html

4. 在集成的过程中出现的问题

一开始使用的SpringBoot版本是2.7.0

在项目启动时，出现错误

在之前集成的时候，使用的SpringBoot版本是2.5.6，就没有遇到上面的错误

后来去网上百度时，出现这个问题的原因是

SpringBoot 2.6.0中将SpringMVC的默认路径匹配策略从AntPathMatcher更改为PathPatternParser，导致出错。

解决办法是：切回原先的AntPathMatcher

采用降低SpringBoot的版本或者更改路径匹配策略，都可吧。后者对于以后的使用上未知。

除去以上两种方式，还有未验证的一种方式

添加对guava的依赖

<dependency><groupId>com.google.guava</groupId><artifactId>guava</artifactId><version>25.1-jre</version></dependency>

二、集成Swagger3

1. pom引用

<properties><java.version>1.8</java.version><springfox.version>3.0.0</springfox.version><fastjson.version>1.2.75</fastjson.version><hutool.version>5.7.16</hutool.version></properties><dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-web</artifactId></dependency><dependency><groupId>org.hibernate.validator</groupId><artifactId>hibernate-validator</artifactId></dependency><dependency><groupId>io.springfox</groupId><artifactId>springfox-boot-starter</artifactId><version>${springfox.version}</version></dependency><dependency><groupId>org.projectlombok</groupId><artifactId>lombok</artifactId><optional>true</optional></dependency><dependency><groupId>com.alibaba</groupId><artifactId>fastjson</artifactId><version>${fastjson.version}</version></dependency><dependency><groupId>cn.hutool</groupId><artifactId>hutool-all</artifactId><version>${hutool.version}</version></dependency>

与上面Swagger2不同之处在于，由两个引用替换成了一个springfox-boot-starter引用

2. Swagger3配置类

在Swagger3中如果使用默认的配置，是不需要Configuration的配置类

在Springfox的介绍中，移除了@EnableSwagger2 注解

不需要配置类，直接启动项目即可

3. 访问Swagger3页面

访问地址：http://localhost:8080/swagger-ui/

在界面上与Swagger2稍微有点不同

4. 在集成的过程中出现的问题

同上，也出现过类加载的问题

可以使用前两种方案解决

三、Swagger使用

关于使用，不再区分swagger2或者swagger3。

估计使用上大面上是一致的

1. 配置文档信息

1.1 在swagger2中

packagecom.example.config;
importorg.springframework.context.annotation.Bean;
importorg.springframework.context.annotation.Configuration;
importspringfox.documentation.service.ApiInfo;
importspringfox.documentation.service.Contact;
importspringfox.documentation.spi.DocumentationType;
importspringfox.documentation.spring.web.plugins.Docket;
importspringfox.documentation.swagger2.annotations.EnableSwagger2;
importjava.util.concurrent.CopyOnWriteArrayList;
@Configuration@EnableSwagger2publicclassSwaggerConfig {
@BeanpublicDocketdocket() {
returnnewDocket(DocumentationType.SWAGGER_2).apiInfo(apiInfo());
    }
privateApiInfoapiInfo() {
Contactcontact=newContact("阿里云", "https://www.aliyun.com/", "");
returnnewApiInfo(
//标题"文档标题",
//描述"文档描述",
//版本"文档版本1.0.0",
//组织连接"https://www.aliyun.com/",
//联系人信息contact,
//许可证"Apache 2.0 许可",
//许可连接"http://www.apache.org/licenses/LICENSE-2.0",
//扩展newCopyOnWriteArrayList<>());
    }
}

1.2 在swagger3中

packagecom.example.config;
importorg.springframework.context.annotation.Bean;
importorg.springframework.context.annotation.Configuration;
importspringfox.documentation.service.ApiInfo;
importspringfox.documentation.service.Contact;
importspringfox.documentation.spi.DocumentationType;
importspringfox.documentation.spring.web.plugins.Docket;
importjava.util.concurrent.CopyOnWriteArrayList;
@ConfigurationpublicclassSwaggerConfig {
@BeanpublicDocketdocket() {
returnnewDocket(DocumentationType.OAS_30).apiInfo(apiInfo());
    }
privateApiInfoapiInfo() {
Contactcontact=newContact("阿里云", "https://www.aliyun.com/", "");
returnnewApiInfo(
//标题"文档标题",
//描述"文档描述",
//版本"文档版本1.0.0",
//组织连接"https://www.aliyun.com/",
//联系人信息contact,
//许可证"Apache 2.0 许可",
//许可连接"http://www.apache.org/licenses/LICENSE-2.0",
//扩展newCopyOnWriteArrayList<>());
    }
}

1.3 页面展示

2. 配置接口扫描

@BeanpublicDocketdocket() {
// DocumentationType版本的区别returnnewDocket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            .select()
            .apis(RequestHandlerSelectors.basePackage("com.example"))
            .build();
}

在select()和build()之间加入才生效

apis()的参数

any() 配置扫描所有
none() 不扫描接口
withMethodAnnotation() 配置扫描指定的方法注解
withClassAnnotation() 配置扫描指定的类注解
basePackage() 配置扫描指定的包路径

3. 配置接口扫描的path

@BeanpublicDocketdocket() {
// DocumentationType版本的区别returnnewDocket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            .select()
            .apis(RequestHandlerSelectors.basePackage("com.example"))
            .paths(PathSelectors.any())
            .build();
}

paths()的参数

any() 任何请求都扫描
none() 任何请求都不扫描
regex() 符合正则表达式的
ant() 符合ant的路径

4. 配置Api的分组

在没有配置分组时，默认是default。可以通过groupName()方法设置分组

@BeanpublicDocketdocket() {
returndocketGroup("");
}
@BeanpublicDocketdocket1() {
returndocketGroup("group1");
}
@BeanpublicDocketdocket2() {
returndocketGroup("group2");
}
privateDocketdocketGroup(StringgroupName) {
Docketdocket=newDocket(DocumentationType.OAS_30);
if (StrUtil.isNotBlank(groupName)) {
docket.groupName(groupName);
    }
docket.apiInfo(apiInfo())
            .select()
            .apis(RequestHandlerSelectors.basePackage("com.example"))
            .paths(PathSelectors.any())
            .build();
returndocket;
}

指定三个分组，分别：default、group1、group2。

5. 配置是否开启Swagger

可以通过enable()方法来配置是否开启swagger

/*** Hook to externally control auto initialization of this swagger plugin instance.* Typically used if defer initialization.** @param externallyConfiguredFlag - true to turn it on, false to turn it off* @return this Docket*/publicDocketenable(booleanexternallyConfiguredFlag) {
this.enabled=externallyConfiguredFlag;
returnthis;
}

配置default、dev、test环境开启Swagger

@BeanpublicDocketdocket(Environmentenv) {
returndocketGroup("")
            .enable(env.acceptsProfiles(Profiles.of("default", "dev", "test")));
}

配置的参数即spring.profiles.active指定的值，不指定，默认值为default

6. Controller接口创建

packagecom.example.controller;
importcom.example.entity.Student;
importio.swagger.annotations.Api;
importio.swagger.annotations.ApiOperation;
importlombok.AllArgsConstructor;
importlombok.extern.slf4j.Slf4j;
importorg.springframework.validation.annotation.Validated;
importorg.springframework.web.bind.annotation.GetMapping;
importorg.springframework.web.bind.annotation.RequestMapping;
importorg.springframework.web.bind.annotation.RestController;
importjavax.validation.Valid;
@Slf4j@Valid@Validated@RestController@AllArgsConstructor@RequestMapping("/api")
@Api(value="3.0版本api请求", tags="3.0版本api请求")
publicclassApiController {
@GetMapping("/test")
@ApiOperation(value="3.0测试接口", notes="该接口的描述")
publicStringtest() {
return"test";
    }
@GetMapping("/student")
@ApiOperation(value="学生类接口", notes="获取一个学生对象")
publicStudentstudent() {
Studentstudent=newStudent();
student.setName("张三");
student.setAge(18);
returnstudent;
    }
}

Student学生实体类

packagecom.example.entity;
importio.swagger.annotations.ApiModel;
importio.swagger.annotations.ApiModelProperty;
importlombok.Data;
@Data@ApiModel(value="学生类实体")
publicclassStudent {
@ApiModelProperty("姓名")
privateStringname;
@ApiModelProperty("年龄")
privateIntegerage;
}

7. Swagger的不同ui风格

7.1 默认ui

访问地址：http://localhost:8080/swagger-ui/

<dependency><groupId>io.springfox</groupId><artifactId>springfox-boot-starter</artifactId><version>${springfox.version}</version></dependency>

7.2 bootstrap ui

访问地址：http://localhost:8080/doc.html

<dependency><groupId>com.github.xiaoymin</groupId><artifactId>swagger-bootstrap-ui</artifactId><version>1.9.6</version></dependency>

后来被knife4j代替

7.3 Layui ui

访问地址：http://localhost:8080/docs.html

<dependency><groupId>com.github.caspar-chen</groupId><artifactId>swagger-ui-layer</artifactId><version>1.1.3</version></dependency>

这个基于Layui的好像不能切换分组，没找到切换分组的地方.

更不幸的是，这个项目已经停止维护了

7.4 knife4j

https://doc.xiaominfo.com/knife4j/documentation/

集成的选择比较多，可以自行选择。

此外，衍生出来的功能也比较多，可以尝试去探索。

更可以参考网站文档去使用：https://doc.xiaominfo.com/knife4j/documentation/

四、关于Swagger2和Swagger3

https://github.com/springfox/springfox

SpringBoot中集成Swagger

一、集成Swagger2

1. pom引用

2. Swagger2配置类

3. 访问Swagger2页面

4. 在集成的过程中出现的问题

二、集成Swagger3

1. pom引用

2. Swagger3配置类

3. 访问Swagger3页面

4. 在集成的过程中出现的问题

三、Swagger使用

1. 配置文档信息

1.1 在swagger2中

1.2 在swagger3中

1.3 页面展示

2. 配置接口扫描

3. 配置接口扫描的path

4. 配置Api的分组

5. 配置是否开启Swagger

6. Controller接口创建

7. Swagger的不同ui风格

7.1 默认ui

7.2 bootstrap ui

7.3 Layui ui

7.4 knife4j

四、关于Swagger2和Swagger3

热门文章

最新文章

相关课程

相关电子书

相关实验场景