SpringBoot集成SpringDoc和Knife4j
目录
警告
本文最后更新于 2023-03-05，文中内容可能已过时，请谨慎使用。
对于SpringBoot2.6.x以上的版本，集成Swagger有各种各样的依赖报错问题，
Springfox2020年7月起不再更新，所以为了后续SpringBoot版本的接口文档生成，改为集成springdoc
springdoc支持 Open API 3、Swagger-ui等，可以很方便与SpringBoot整合，配置和使用与 Springfox Swagger2 类似。
添加依赖
添加最新的springdoc-openapi-ui
<dependency>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-ui</artifactId>
<version>1.6.14</version>
</dependency>
application.yml添加下面内容
springdoc:
packages-to-scan: cc.bnblogs.swagger_study.controller
swagger-ui:
enabled: true
配置类
@Configuration
public class SpringDocConfig {
private static final String TITLE = "SpringBoot集成SpringDoc";
private static final String DESCRIPTION = "简单使用入门";
private static final String VERSION = "1.0";
private static final String WEBSITE_NAME = "blog";
private static final String WEBSITE_URL = "https://hugo.bnblogs.cc";
@Bean
public OpenAPI myOpenAPI() {
return new OpenAPI()
.info(new Info().title(TITLE)
.description(DESCRIPTION)
.version(VERSION))
.externalDocs(new ExternalDocumentation().description(WEBSITE_NAME)
.url(WEBSITE_URL));
}
}
可以把前面写的 SpringDocConfig提取到公共模块中，通过maven依赖引用，在application.yml 中配置不同的变量
可以加入下面的依赖，这样在application.yml编写元数据的时候有提示
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-configuration-processor</artifactId>
<optional>true</optional>
</dependency>
将SpringDocConfig中的固定属性提取到DocInfo.java中
@Data
@Component
@ConfigurationProperties(prefix = "doc-info")
public class DocInfo {
private String title = "SpringBoot集成SpringDoc";
private String description = "简单使用入门";
private String version = "1.0";
private String websiteName = "blog";
private String websiteUrl = "https://hugo.bnblogs.cc";
}
修改后的SpringDocConfig.java
@Configuration
public class SpringDocConfig {
@Autowired
private DocInfo docInfo;
@Bean
public OpenAPI myOpenAPI() {
return new OpenAPI()
.info(new Info().title(docInfo.getTitle())
.description(docInfo.getDescription())
.version(docInfo.getVersion()))
.externalDocs(new ExternalDocumentation().description(docInfo.getWebsiteName())
.url(docInfo.getWebsiteUrl()));
}
}
在application.yml可以覆盖对应的属性值
doc-info:
title: SpringDoc使用
description: 基于Spring Boot 2.7.9
version: 1.2
website-name: bnblogs
website-url: https://bnblogs.cc
访问地址：http://localhost:8080/swagger-ui/index.html
接口区别
| swagger 2 | OpenApi3 (swagger 3) | 描述 |
|---|---|---|
@Api |
@Tag |
修饰controller类，类的说明 |
@ApiOperation |
@Operation |
修饰controller中的接口方法，接口的说明 |
@ApiModel |
@Schema |
修饰实体类，该实体的说明 |
@ApiModelProperty |
@Schema |
修饰实体类的属性，实体类中属性的说明 |
@ApiImplicitParams |
@Parameters |
接口参数集合 |
@ApiImplicitParam |
@Parameter |
接口参数 |
@ApiParam |
@Parameter |
接口参数 |
集成knife4j的ui
导入依赖
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-springdoc-ui</artifactId>
<version>3.0.3</version>
</dependency>
如果要使用knife4j，Spring Doc的配置中必须添加分组配置，我们这里分别添加hello、demo、all三个分组。hello分组对应HelloController下的接口，demo分组对应DemoController下的接口，all展示所有接口。
package cc.bnblogs.swagger_study.config;
import io.swagger.v3.oas.models.ExternalDocumentation;
import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Info;
import org.springdoc.core.GroupedOpenApi;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
@Configuration
public class SpringDocConfig {
@Autowired
private DocInfo docInfo;
@Bean
public OpenAPI myOpenAPI() {
return new OpenAPI()
.info(new Info().title(docInfo.getTitle())
.description(docInfo.getDescription())
.version(docInfo.getVersion()))
.externalDocs(new ExternalDocumentation().description(docInfo.getWebsiteName())
.url(docInfo.getWebsiteUrl()));
}
@Bean
public GroupedOpenApi allApi() {
return GroupedOpenApi.builder()
.group("all")
.pathsToMatch("/**")
.build();
}
@Bean
public GroupedOpenApi DemoApi() {
return GroupedOpenApi.builder()
.group("demo")
.pathsToMatch("/demo/**")
.build();
}
@Bean
public GroupedOpenApi helloApi() {
return GroupedOpenApi.builder()
.group("hello")
.pathsToMatch("/hello/**")
.build();
}
}
访问地址: http://localhost:8080/doc.html
配置成功的页面如下:
