1今膊、依賴
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-boot-starter</artifactId>
<version>3.0.0</version>
</dependency>
注：Springfox 3.0.0（包含springfox-swagger2-3.0.0）即OpenAPI 3的發(fā)布與系統(tǒng)集成
啟動項目浩姥，訪問地址：http://localhost:8080/swagger-ui/index.html
2讶请、application.yml配置
spring:
application:
name: springfox-swagger
server:
port: 8080
# ===== 自定義swagger配置 ===== #
swagger:
enable: true
application-name: ${spring.application.name}
application-version: 1.0
application-description: springfox swagger 3.0整合Demo
try-host: http://localhost:${server.port}
3、自定義swagger配置類SwaggerProperties
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.stereotype.Component;
/**
* @author: fjq
* @date: 2021/2/8 11:24
*/
@Component
@ConfigurationProperties("swagger")
public class SwaggerProperties {
/**
* 是否開啟swagger，生產(chǎn)環(huán)境一般關(guān)閉嚷狞，所以這里定義一個變量
*/
private Boolean enable;
/**
* 項目應(yīng)用名
*/
private String applicationName;
/**
* 項目版本信息
*/
private String applicationVersion;
/**
* 項目描述信息
*/
private String applicationDescription;
/**
* 接口調(diào)試地址
*/
private String tryHost;
public Boolean getEnable() {
return enable;
}
public void setEnable(Boolean enable) {
this.enable = enable;
}
public String getApplicationName() {
return applicationName;
}
public void setApplicationName(String applicationName) {
this.applicationName = applicationName;
}
public String getApplicationVersion() {
return applicationVersion;
}
public void setApplicationVersion(String applicationVersion) {
this.applicationVersion = applicationVersion;
}
public String getApplicationDescription() {
return applicationDescription;
}
public void setApplicationDescription(String applicationDescription) {
this.applicationDescription = applicationDescription;
}
public String getTryHost() {
return tryHost;
}
public void setTryHost(String tryHost) {
this.tryHost = tryHost;
}
}
4、配置類SwaggerConfiguration
import io.swagger.models.auth.In;
import org.apache.commons.lang3.reflect.FieldUtils;
import org.springframework.boot.SpringBootVersion;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.util.ReflectionUtils;
import org.springframework.web.servlet.config.annotation.InterceptorRegistration;
import org.springframework.web.servlet.config.annotation.InterceptorRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.oas.annotations.EnableOpenApi;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.ApiKey;
import springfox.documentation.service.AuthorizationScope;
import springfox.documentation.service.Contact;
import springfox.documentation.service.SecurityReference;
import springfox.documentation.service.SecurityScheme;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spi.service.contexts.SecurityContext;
import springfox.documentation.spring.web.plugins.Docket;
import java.lang.reflect.Field;
import java.util.Arrays;
import java.util.Collections;
import java.util.LinkedHashSet;
import java.util.List;
import java.util.Set;
/**
* 基于Swagger生成API文檔
*
* @EnableOpenApi：啟動OpenApi的類荣堰； 之前是@EnableSwagger2
* @author: fjq
* @date: 2021/2/8 11:19
*/
@EnableOpenApi
@Configuration
public class SwaggerConfiguration implements WebMvcConfigurer {
private final SwaggerProperties swaggerProperties;
public SwaggerConfiguration(SwaggerProperties swaggerProperties) {
this.swaggerProperties = swaggerProperties;
}
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.OAS_30).pathMapping("/")
// 定義是否開啟swagger感耙，false為關(guān)閉，可以通過變量控制
.enable(swaggerProperties.getEnable())
// 將api的元信息設(shè)置為包含在json ResourceListing響應(yīng)中持隧。
.apiInfo(apiInfo())
// 接口調(diào)試地址
.host(swaggerProperties.getTryHost())
// 選擇哪些接口作為swagger的doc發(fā)布
.select()
.apis(RequestHandlerSelectors.any())
.paths(PathSelectors.any())
.build()
// 支持的通訊協(xié)議集合
.protocols(newHashSet("https", "http"))
// 授權(quán)信息設(shè)置即硼，必要的header token等認(rèn)證信息
.securitySchemes(securitySchemes())
// 授權(quán)信息全局應(yīng)用
.securityContexts(securityContexts());
}
/**
* API 頁面上半部分展示信息
*/
private ApiInfo apiInfo() {
return new ApiInfoBuilder().title(swaggerProperties.getApplicationName() + " Api Doc")
.description(swaggerProperties.getApplicationDescription())
.contact(new Contact("lighter", null, "123456@gmail.com"))
.version("Application Version: " + swaggerProperties.getApplicationVersion() + ", Spring Boot Version: " + SpringBootVersion.getVersion())
.build();
}
/**
* 設(shè)置授權(quán)信息
*/
private List<SecurityScheme> securitySchemes() {
ApiKey apiKey = new ApiKey("BASE_TOKEN", "token", In.HEADER.toValue());
return Collections.singletonList(apiKey);
}
/**
* 授權(quán)信息全局應(yīng)用
*/
private List<SecurityContext> securityContexts() {
return Collections.singletonList(
SecurityContext.builder()
.securityReferences(Collections.singletonList(new SecurityReference("BASE_TOKEN", new AuthorizationScope[]{new AuthorizationScope("global", "")})))
.build()
);
}
@SafeVarargs
private final <T> Set<T> newHashSet(T... ts) {
if (ts.length > 0) {
return new LinkedHashSet<>(Arrays.asList(ts));
}
return null;
}
/**
* 通用攔截器排除swagger設(shè)置，所有攔截器都會自動加swagger相關(guān)的資源排除信息
*/
@SuppressWarnings("unchecked")
@Override
public void addInterceptors(InterceptorRegistry registry) {
try {
Field registrationsField = FieldUtils.getField(InterceptorRegistry.class, "registrations", true);
List<InterceptorRegistration> registrations = (List<InterceptorRegistration>) ReflectionUtils.getField(registrationsField, registry);
if (registrations != null) {
for (InterceptorRegistration interceptorRegistration : registrations) {
interceptorRegistration
.excludePathPatterns("/swagger**/**")
.excludePathPatterns("/webjars/**")
.excludePathPatterns("/v3/**")
.excludePathPatterns("/doc.html");
}
}
} catch (Exception e) {
e.printStackTrace();
}
}
}
5屡拨、配置類接口ApiImplicitParam
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
/**
* swagger2
*
* @author: fjq
* @date: 2021/2/8 11:17
*/
@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
public @interface ApiImplicitParam {
//參數(shù)名
String name() default "";
//參數(shù)描述
String value() default "";
//參數(shù)默認(rèn)值
String defaultValue() default "";
String allowableValues() default "";
//是否必傳
boolean required() default false;
String access() default "";
//允許多個只酥，當(dāng)傳入的參數(shù)為數(shù)組或者list時候，指定參數(shù)類型dataType()呀狼，屬性設(shè)置為true裂允；
boolean allowMultiple() default false;
//數(shù)據(jù)類型：這可以是類名或基礎(chǔ)類型。
String dataType() default "";
//數(shù)據(jù)的class類
Class<?> dataTypeClass() default Void.class;
/**
* 請求參數(shù)類型：
* path：請求參數(shù)的獲雀缤А：@PathVariable
* query：請求參數(shù)的獲染唷：@RequestParam
* body：@RequestBody
* header：請求參數(shù)的獲取：@RequestHeader
* form：表單數(shù)據(jù)
*/
String paramType() default "";
/**
* a single example for non-body type parameters
*/
String example() default "";
//Examples for the parameter. Applies only to BodyParameters
// Example examples() default @Example(value = @ExampleProperty(mediaType = "", value = ""));
//Adds the ability to override the detected type
String type() default "";
//Adds the ability to provide a custom format
String format() default "";
//Adds the ability to set a format as empty
boolean allowEmptyValue() default false;
//adds ability to be designated as read only.
boolean readOnly() default false;
//adds ability to override collectionFormat with `array` types
String collectionFormat() default "";
}
4貌踏、main方法
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
@SpringBootApplication
public class SwaggerApplication {
public static void main(String[] args) {
SpringApplication.run(SwaggerApplication.class, args);
}
}
