重磅：Swagger3.0 官方 starter 誕生了，其它的都可以扔了~
阿新 • • 發佈：2020-10-14
- 資料
- swagger介紹
- springfox介紹
- SpringFox 3.0.0 釋出
- 整合使用
- 一些常用註解說明
- 示例
- 參考
資料
- swagger 官網：swagger.io
- springfox 官網：springfox
- springfox Github 倉庫：springfox / springfox
- springfox-demos Github 倉庫：springfox / springfox-demos
- springfox Maven 倉庫：Home » io.springfox
swagger介紹
對於 Rest API 來說很重要的一部分內容就是文件，Swagger 為我們提供了一套通過程式碼和註解自動生成文件的方法，這一點對於保證 API 文件的及時性將有很大的幫助。
Swagger 是一套基於 OpenAPI 規範（OpenAPI Specification，OAS）構建的開源工具，可以幫助我們設計、構建、記錄以及使用 Rest API。
OAS本身是一個API規範，它用於描述一整套API介面，包括一個介面是哪種請求方式、哪些引數、哪些header等，都會被包括在這個檔案中。它在設計的時候通常是YAML格式，這種格式書寫起來比較方便，而在網路中傳輸時又會以json形式居多，因為json的通用性比較強。
Swagger 主要包含了以下三個部分：
- Swagger Editor：基於瀏覽器的編輯器，我們可以使用它編寫我們 OpenAPI 規範。
- Swagger UI：它會將我們編寫的 OpenAPI 規範呈現為互動式的 API 文件，後文我將使用瀏覽器來檢視並且操作我們的 Rest API。
- Swagger Codegen：它可以通過為 OpenAPI（以前稱為 Swagger）規範定義的任何 API 生成伺服器存根和客戶端 SDK 來簡化構建過程。
springfox介紹
由於Spring的流行，Marty Pitt編寫了一個基於Spring的元件swagger-springmvc，用於將swagger整合到springmvc中來，而springfox則是從這個元件發展而來。
通常SpringBoot專案整合swagger需要用到兩個依賴：springfox-swagger2和springfox-swagger-ui，用於自動生成swagger文件。
- springfox-swagger2：這個元件的功能用於幫助我們自動生成描述API的json檔案
- springfox-swagger-ui：就是將描述API的json檔案解析出來，用一種更友好的方式呈現出來。
SpringFox 3.0.0 釋出
官方說明：
- SpringFox 3.0.0 釋出了，SpringFox 的前身是 swagger-springmvc，是一個開源的 API doc 框架，可以將 Controller 的方法以文件的形式展現。
- 首先，非常感謝社群讓我有動力參與這個專案。在這個版本中，在程式碼、註釋、bug報告方面有一些非常驚人的貢獻，看到人們在問題論壇上跳槽來解決問題，我感到很謙卑。它確實激勵我克服“困難”，開始認真地工作。有什麼更好的辦法來擺脫科維德的憂鬱！
- 注意：這是一個突破性的變更版本，我們已經儘可能地保持與springfox早期版本的向後相容性。在2.9之前被棄用的api已經被積極地刪除，並且標記了將在不久的將來消失的新api。所以請注意這些，並報告任何遺漏的內容。
新特性：
- Remove explicit dependencies on springfox-swagger2
- Remove any @EnableSwagger2… annotations
- Add the springfox-boot-starter dependency
- Springfox 3.x removes dependencies on guava and other 3rd party libraries (not zero dep yet! depends on spring plugin and open api libraries for annotations and models) so if you used guava predicates/functions those will need to transition to java 8 function interfaces.
此版本的亮點：
- Spring5，Webflux支援（僅支援請求對映，尚不支援功能端點）。
- Spring Integration支援（非常感謝反饋）。
- SpringBoot支援
springfox Boot starter依賴性（零配置、自動配置支援）。 - 具有自動完成功能的文件化配置屬性。
- 更好的規範相容性與2.0。
- 支援OpenApi 3.0.3。
- 零依賴。幾乎只需要spring-plugin，swagger-core ，現有的swagger2註釋將繼續工作並豐富openapi3.0規範。
相容性說明：
- 需要Java 8
- 需要Spring5.x（未在早期版本中測試）
- 需要SpringBoot 2.2+（未在早期版本中測試）
注意：
應用主類增加註解@EnableOpenApi，刪除之前版本的SwaggerConfig.java。
啟動專案，訪問地址：http://localhost:8080/swagger-ui/index.html，注意2.x版本中訪問的地址的為http://localhost:8080/swagger-ui.html
整合使用
Maven專案中引入springfox-boot-starter依賴：
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-boot-starter</artifactId>
<version>3.0.0</version>
</dependency>
12345
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:springfoxswagger3.0整合Demo
try-host:http://localhost:${server.port}
12345678910111213
使用@EnableOpenApi註解，啟用swagger配置
@EnableOpenApi
@Configuration
publicclassSwaggerConfiguration{
}
12345
自定義swagger配置類SwaggerProperties
@Component
@ConfigurationProperties("swagger")
publicclassSwaggerProperties{
/**
*是否開啟swagger，生產環境一般關閉，所以這裡定義一個變數
*/
privateBooleanenable;
/**
*專案應用名
*/
privateStringapplicationName;
/**
*專案版本資訊
*/
privateStringapplicationVersion;
/**
*專案描述資訊
*/
privateStringapplicationDescription;
/**
*介面除錯地址
*/
privateStringtryHost;
publicBooleangetEnable(){
returnenable;
}
publicvoidsetEnable(Booleanenable){
this.enable=enable;
}
publicStringgetApplicationName(){
returnapplicationName;
}
publicvoidsetApplicationName(StringapplicationName){
this.applicationName=applicationName;
}
publicStringgetApplicationVersion(){
returnapplicationVersion;
}
publicvoidsetApplicationVersion(StringapplicationVersion){
this.applicationVersion=applicationVersion;
}
publicStringgetApplicationDescription(){
returnapplicationDescription;
}
publicvoidsetApplicationDescription(StringapplicationDescription){
this.applicationDescription=applicationDescription;
}
publicStringgetTryHost(){
returntryHost;
}
publicvoidsetTryHost(StringtryHost){
this.tryHost=tryHost;
}
}
1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768
一個完整詳細的springfox swagger配置示例：
importio.swagger.models.auth.In;
importorg.apache.commons.lang3.reflect.FieldUtils;
importorg.springframework.boot.SpringBootVersion;
importorg.springframework.context.annotation.Bean;
importorg.springframework.context.annotation.Configuration;
importorg.springframework.util.ReflectionUtils;
importorg.springframework.web.servlet.config.annotation.InterceptorRegistration;
importorg.springframework.web.servlet.config.annotation.InterceptorRegistry;
importorg.springframework.web.servlet.config.annotation.WebMvcConfigurer;
importspringfox.documentation.builders.ApiInfoBuilder;
importspringfox.documentation.builders.PathSelectors;
importspringfox.documentation.builders.RequestHandlerSelectors;
importspringfox.documentation.oas.annotations.EnableOpenApi;
importspringfox.documentation.service.*;
importspringfox.documentation.spi.DocumentationType;
importspringfox.documentation.spi.service.contexts.SecurityContext;
importspringfox.documentation.spring.web.plugins.Docket;
importjava.lang.reflect.Field;
importjava.util.*;
@EnableOpenApi
@Configuration
publicclassSwaggerConfigurationimplementsWebMvcConfigurer{
privatefinalSwaggerPropertiesswaggerProperties;
publicSwaggerConfiguration(SwaggerPropertiesswaggerProperties){
this.swaggerProperties=swaggerProperties;
}
@Bean
publicDocketcreateRestApi(){
returnnewDocket(DocumentationType.OAS_30).pathMapping("/")
//定義是否開啟swagger，false為關閉，可以通過變數控制
.enable(swaggerProperties.getEnable())
//將api的元資訊設定為包含在json ResourceListing響應中。
.apiInfo(apiInfo())
//介面除錯地址
.host(swaggerProperties.getTryHost())
//選擇哪些介面作為swagger的doc釋出
.select()
.apis(RequestHandlerSelectors.any())
.paths(PathSelectors.any())
.build()
//支援的通訊協議集合
.protocols(newHashSet("https","http"))
//授權資訊設定，必要的headertoken等認證資訊
.securitySchemes(securitySchemes())
//授權資訊全域性應用
.securityContexts(securityContexts());
}
/**
*API頁面上半部分展示資訊
*/
privateApiInfoapiInfo(){
returnnewApiInfoBuilder().title(swaggerProperties.getApplicationName()+"ApiDoc")
.description(swaggerProperties.getApplicationDescription())
.contact(newContact("lighter",null,"[email protected]"))
.version("ApplicationVersion:"+swaggerProperties.getApplicationVersion()+",SpringBootVersion:"+SpringBootVersion.getVersion())
.build();
}
/**
*設定授權資訊
*/
privateList<SecurityScheme>securitySchemes(){
ApiKeyapiKey=newApiKey("BASE_TOKEN","token",In.HEADER.toValue());
returnCollections.singletonList(apiKey);
}
/**
*授權資訊全域性應用
*/
privateList<SecurityContext>securityContexts(){
returnCollections.singletonList(
SecurityContext.builder()
.securityReferences(Collections.singletonList(newSecurityReference("BASE_TOKEN",newAuthorizationScope[]{newAuthorizationScope("global","")})))
.build()
);
}
@SafeVarargs
privatefinal<T>Set<T>newHashSet(T...ts){
if(ts.length>0){
returnnewLinkedHashSet<>(Arrays.asList(ts));
}
returnnull;
}
/**
*通用攔截器排除swagger設定，所有攔截器都會自動加swagger相關的資源排除資訊
*/
@SuppressWarnings("unchecked")
@Override
publicvoidaddInterceptors(InterceptorRegistryregistry){
try{
FieldregistrationsField=FieldUtils.getField(InterceptorRegistry.class,"registrations",true);
List<InterceptorRegistration>registrations=(List<InterceptorRegistration>)ReflectionUtils.getField(registrationsField,registry);
if(registrations!=null){
for(InterceptorRegistrationinterceptorRegistration:registrations){
interceptorRegistration
.excludePathPatterns("/swagger**/**")
.excludePathPatterns("/webjars/**")
.excludePathPatterns("/v3/**")
.excludePathPatterns("/doc.html");
}
}
}catch(Exceptione){
e.printStackTrace();
}
}
}
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121
一些常用註解說明
- @Api：用在controller類，描述API介面
- @ApiOperation：描述介面方法
- @ApiModel：描述物件
- @ApiModelProperty：描述物件屬性
- @ApiImplicitParams：描述介面引數
- @ApiResponses：描述介面響應
- @ApiIgnore：忽略介面方法
示例
專案Demo：springfox-swagger
效果圖：
參考
- 在 Spring Boot 專案中使用 Swagger 文件
- Springfox 3.0.0（包含springfox-swagger2-3.0.0）即OpenAPI 3的釋出與系統整合