當(dāng)前位置：首頁 > 單片機 > 架構(gòu)師社區(qū)

Swagger3.0?天天刷屏，真的香嗎？

時間：2021-08-19 16:27:59

關(guān)鍵字： ge

手機看文章

掃描二維碼
隨時隨地手機看文章

[導(dǎo)讀]目錄前言官方文檔如何說？SpringBoot版本說明添加依賴springfox-boot-starter做了什么？擼起袖子就是干？定制一個基本的文檔示例文檔如何分組？如何添加授權(quán)信息？如何攜帶公共的請求參數(shù)？粗略是一個BUG總結(jié)前言最近頻繁被Swagger3.0刷屏，官方表示這是...

前言

官方文檔如何說？

該項目開源在Github上，地址：https://github.com/springfox/springfox。

Swagger 3.0有何改動？官方文檔總結(jié)如下幾點：

刪除了對springfox-swagger2的依賴
刪除所有@EnableSwagger2...注解
添加了springfox-boot-starter依賴項
移除了guava等第三方依賴
文檔訪問地址改變了，改成了http://ip:port/project/swagger-ui/index.html。

姑且看到這里，各位初始感覺如何？

既然人家更新出來了，咱不能不捧場，下面就介紹下Spring Boot如何整合Swagger 3.0吧。

Spring Boot版本說明

作者使用Spring Boot的版本是2.3.5.RELEASE

添加依賴

Swagger 3.0已經(jīng)有了與Spring Boot整合的啟動器，只需要添加以下依賴：

??<dependency>
???????<groupId>io.springfoxgroupId>
???????<artifactId>springfox-boot-starterartifactId>
???????<version>3.0.0version>
??dependency>

springfox-boot-starter做了什么？

Swagger 3.0主推的一大特色就是這個啟動器，那么這個啟動器做了什么呢？

「記住」：啟動器的一切邏輯都在自動配置類中。

找到springfox-boot-starter的自動配置類，在/META-INF/spring.factories文件中，如下：

從上圖可以知道，自動配置類就是OpenApiAutoConfiguration，源碼如下：

@Configuration
@EnableConfigurationProperties(SpringfoxConfigurationProperties.class)
@ConditionalOnProperty(value?=?"springfox.documentation.enabled",?havingValue?=?"true",?matchIfMissing?=?true)
@Import({
????OpenApiDocumentationConfiguration.class,
????SpringDataRestConfiguration.class,
????BeanValidatorPluginsConfiguration.class,
????Swagger2DocumentationConfiguration.class,
????SwaggerUiWebFluxConfiguration.class,
????SwaggerUiWebMvcConfiguration.class
})
@AutoConfigureAfter({?WebMvcAutoConfiguration.class,?JacksonAutoConfiguration.class,
????HttpMessageConvertersAutoConfiguration.class,?RepositoryRestMvcAutoConfiguration.class?})
public?class?OpenApiAutoConfiguration?{

}

敢情這個自動配置類啥也沒干，就光導(dǎo)入了幾個配置類(@Import)以及開啟了屬性配置(@EnableConfigurationProperties)。

「重點」：記住OpenApiDocumentationConfiguration這個配置類，初步看來這是個BUG，本人也不想深入，里面的代碼寫的實在拙劣，注釋都不寫。

擼起袖子就是干？

說真的，還是和以前一樣，真的沒什么太大的改變，按照文檔的步驟一步步來。

定制一個基本的文檔示例

一切的東西還是需要配置類手動配置，說真的，我以為會在全局配置文件中自己配置就行了。哎，想多了。配置類如下：

@EnableOpenApi
@Configuration
@EnableConfigurationProperties(value?=?{SwaggerProperties.class})
public?class?SwaggerConfig?{
??/**
?????*?配置屬性
?????*/
????@Autowired
????private?SwaggerProperties?properties;

????@Bean
????public?Docket?frontApi()?{
????????return?new?Docket(DocumentationType.OAS_30)
????????????????//是否開啟，根據(jù)環(huán)境配置
????????????????.enable(properties.getFront().getEnable())
????????????????.groupName(properties.getFront().getGroupName())
????????????????.apiInfo(frontApiInfo())
????????????????.select()
????????????????//指定掃描的包
????????????????.apis(RequestHandlerSelectors.basePackage(properties.getFront().getBasePackage()))
????????????????.paths(PathSelectors.any())
????????????????.build();
????}

????/**
?????*?前臺API信息
?????*/
????private?ApiInfo?frontApiInfo()?{
????????return?new?ApiInfoBuilder()
????????????????.title(properties.getFront().getTitle())
????????????????.description(properties.getFront().getDescription())
????????????????.version(properties.getFront().getVersion())
????????????????.contact(????//添加開發(fā)者的一些信息
????????????????????????new?Contact(properties.getFront().getContactName(),?properties.getFront().getContactUrl(),
????????????????????????????????properties.getFront().getContactEmail()))
????????????????.build();
????}
}

@EnableOpenApi這個注解文檔解釋如下：

Indicates that Swagger support should be enabled.
This should be applied to a Spring java config and should have an accompanying '@Configuration' annotation.
Loads all required beans defined in @see SpringSwaggerConfig

什么意思呢？大致意思就是「只有在配置類標(biāo)注了@EnableOpenApi這個注解才會生成Swagger文檔」。

@EnableConfigurationProperties這個注解使開啟自定義的屬性配置，這是作者自定義的Swagger配置。

總之還是和之前一樣配置，根據(jù)官方文檔要求，需要在配置類上加一個@EnableOpenApi注解。

文檔如何分組？

我們都知道，一個項目可能分為前臺，后臺，APP端，小程序端.....每個端的接口可能還相同，不可能全部放在一起吧，肯定是要區(qū)分開的。

因此，實際開發(fā)中文檔肯定是要分組的。

分組其實很簡單，Swagger向IOC中注入一個Docket即為一個組的文檔，其中有個groupName()方法指定分組的名稱。

因此只需要注入多個Docket指定不同的組名即可，當(dāng)然，這些文檔的標(biāo)題、描述、掃描的路徑都是可以不同定制的。

如下配置兩個Docket，分為前臺和后臺，配置類如下：

@EnableOpenApi
@Configuration
@EnableConfigurationProperties(value?=?{SwaggerProperties.class})
public?class?SwaggerConfig?{
??/**
?????*?配置屬性
?????*/
????@Autowired
????private?SwaggerProperties?properties;

????@Bean
????public?Docket?frontApi()?{
????????return?new?Docket(DocumentationType.OAS_30)
????????????????//是否開啟，根據(jù)環(huán)境配置
????????????????.enable(properties.getFront().getEnable())
????????????????.groupName(properties.getFront().getGroupName())
????????????????.apiInfo(frontApiInfo())
????????????????.select()
????????????????//指定掃描的包
????????????????.apis(RequestHandlerSelectors.basePackage(properties.getFront().getBasePackage()))
????????????????.paths(PathSelectors.any())
????????????????.build();
????}

????/**
?????*?前臺API信息
?????*/
????private?ApiInfo?frontApiInfo()?{
????????return?new?ApiInfoBuilder()
????????????????.title(properties.getFront().getTitle())
????????????????.description(properties.getFront().getDescription())
????????????????.version(properties.getFront().getVersion())
????????????????.contact(????//添加開發(fā)者的一些信息
????????????????????????new?Contact(properties.getFront().getContactName(),?properties.getFront().getContactUrl(),
????????????????????????????????properties.getFront().getContactEmail()))
????????????????.build();
????}
????
????/**
?????*?后臺API
?????*/
????@Bean
????public?Docket?backApi()?{
????????return?new?Docket(DocumentationType.OAS_30)
????????????????//是否開啟，根據(jù)環(huán)境配置
????????????????.enable(properties.getBack().getEnable())
????????????????.groupName("后臺管理")
????????????????.apiInfo(backApiInfo())
????????????????.select()
????????????????.apis(RequestHandlerSelectors.basePackage(properties.getBack().getBasePackage()))
????????????????.paths(PathSelectors.any())
????????????????.build();
????}
????
????/**
?????*?后臺API信息
?????*/
????private?ApiInfo?backApiInfo()?{
????????return?new?ApiInfoBuilder()
????????????????.title(properties.getBack().getTitle())
????????????????.description(properties.getBack().getDescription())
????????????????.version(properties.getBack().getVersion())
????????????????.contact(????//添加開發(fā)者的一些信息
????????????????????????new?Contact(properties.getBack().getContactName(),?properties.getBack().getContactUrl(),
????????????????????????????????properties.getBack().getContactEmail()))
????????????????.build();
????}
????
}

屬性配置文件SwaggerProperties如下，分為前臺和后臺兩個不同屬性的配置：

/**
?*?swagger的屬性配置類
?*/
@ConfigurationProperties(prefix?=?"spring.swagger")
@Data
public?class?SwaggerProperties?{

????/**
?????*?前臺接口配置
?????*/
????private?SwaggerEntity?front;

????/**
?????*?后臺接口配置
?????*/
????private?SwaggerEntity?back;

????@Data
????public?static?class?SwaggerEntity?{
????????private?String?groupName;
????????private?String?basePackage;
????????private?String?title;
????????private?String?description;
????????private?String?contactName;
????????private?String?contactEmail;
????????private?String?contactUrl;
????????private?String?version;
????????private?Boolean?enable;
????}
}

此時的文檔截圖如下，可以看到有了兩個不同的分組：

如何添加授權(quán)信息？

現(xiàn)在項目API肯定都需要權(quán)限認(rèn)證，否則不能訪問，比如請求攜帶一個TOKEN。

在Swagger中也是可以配置認(rèn)證信息，這樣在每次請求將會默認(rèn)攜帶上。

在Docket中有如下兩個方法指定授權(quán)信息，分別是securitySchemes()和securityContexts()。在配置類中的配置如下，在構(gòu)建Docket的時候設(shè)置進去即可：


????@Bean
????public?Docket?frontApi()?{
????????RequestParameter?parameter?=?new?RequestParameterBuilder()
????????????????.name("platform")
????????????????.description("請求頭")
????????????????.in(ParameterType.HEADER)
????????????????.required(true)
????????????????.build();
????????List?parameters?=?Collections.singletonList(parameter);
????????return?new?Docket(DocumentationType.OAS_30)
????????????????//是否開啟，根據(jù)環(huán)境配置
????????????????.enable(properties.getFront().getEnable())
????????????????.groupName(properties.getFront().getGroupName())
????????????????.apiInfo(frontApiInfo())
????????????????.select()
????????????????//指定掃描的包
????????????????.apis(RequestHandlerSelectors.basePackage(properties.getFront().getBasePackage()))
????????????????.paths(PathSelectors.any())
????????????????.build()
????????????????.securitySchemes(securitySchemes())
????????????????.securityContexts(securityContexts());
????}

????/**
?????*?設(shè)置授權(quán)信息
?????*/
????private?List?securitySchemes()?{
????????ApiKey?apiKey?=?new?ApiKey("BASE_TOKEN",?"token",?In.HEADER.toValue());
????????return?Collections.singletonList(apiKey);
????}

????/**
?????*?授權(quán)信息全局應(yīng)用
?????*/
????private?List?securityContexts()?{
????????return?Collections.singletonList(
????????????????SecurityContext.builder()
????????????????????????.securityReferences(Collections.singletonList(new?SecurityReference("BASE_TOKEN",?new?AuthorizationScope[]{new?AuthorizationScope("global",?"")})))
????????????????????????.build()
????????);
????}

以上配置成功后，在Swagger文檔的頁面中將會有Authorize按鈕，只需要將請求頭添加進去即可。如下圖：

如何攜帶公共的請求參數(shù)？

不同的架構(gòu)可能發(fā)請求的時候除了攜帶TOKEN，還會攜帶不同的參數(shù)，比如請求的平臺，版本等等，這些每個請求都要攜帶的參數(shù)稱之為公共參數(shù)。

那么如何在Swagger中定義公共的參數(shù)呢？比如在請求頭中攜帶。

在Docket中的方法globalRequestParameters()可以設(shè)置公共的請求參數(shù)，接收的參數(shù)是一個List，因此只需要構(gòu)建一個RequestParameter集合即可，如下：

@Bean
public?Docket?frontApi()?{
???//構(gòu)建一個公共請求參數(shù)platform，放在在header
???RequestParameter?parameter?=?new?RequestParameterBuilder()
??????//參數(shù)名稱
??????.name("platform")
??????//描述
??????.description("請求的平臺")
??????//放在header中
??????.in(ParameterType.HEADER)
??????//是否必傳
??????.required(true)
??????.build();
??????//構(gòu)建一個請求參數(shù)集合
??????List?parameters?=?Collections.singletonList(parameter);
????????return?new?Docket(DocumentationType.OAS_30)
????????????????.....
????????????????.build()
????????????????.globalRequestParameters(parameters);
????}

以上配置完成，將會在每個接口中看到一個請求頭，如下圖：

粗略是一個BUG

作者在介紹自動配置類的時候提到了一嘴，現(xiàn)在來簡單分析下。

OpenApiAutoConfiguration這個自動配置類中已經(jīng)導(dǎo)入OpenApiDocumentationConfiguration這個配置類，如下一段代碼：

@Import({
????OpenApiDocumentationConfiguration.class,
????......
})

@EnableOpenApi的源碼如下：

@Retention(value?=?java.lang.annotation.RetentionPolicy.RUNTIME)
@Target(value?=?{java.lang.annotation.ElementType.TYPE})
@Documented
@Import(OpenApiDocumentationConfiguration.class)
public?@interface?EnableOpenApi?{
}

從源碼可以看出：@EnableOpenApi這個注解的作用就是導(dǎo)入OpenApiDocumentationConfiguration這個配置類，納尼？？？

既然已經(jīng)在自動配置類OpenApiAutoConfiguration導(dǎo)入了，那么無論需不需要在配置類上標(biāo)注@EnableOpenApi注解不都會開啟Swagger支持嗎？

「測試一下」：不在配置類上標(biāo)注@EnableOpenApi這個注解，看看是否Swagger運行正常。結(jié)果在意料之中，還是能夠正常運行。

「總結(jié)」：作者只是大致分析了下，這可能是個BUG亦或是后續(xù)有其他的目的，至于結(jié)果如此，不想驗證了，沒什么意思。

總結(jié)

這篇文章也是嘗了個鮮，個人感覺不太香，有點失望。你喜歡嗎？

（全球TMT2022年1月24日訊）The Orangeblowfish（呈合創(chuàng)意設(shè)計（上海）有限公司）在2022年迎來10周歲生日，以全新的形象慶祝10周年，并以粉色作為他們新的品牌色。2012年1月，在毫無相關(guān)行業(yè)...

關(guān)鍵字： ge

Swagger3.0?天天刷屏，真的香嗎？

目錄

前言

官方文檔如何說？

Spring Boot版本說明

添加依賴

springfox-boot-starter做了什么？

擼起袖子就是干？

定制一個基本的文檔示例

文檔如何分組？

如何添加授權(quán)信息？

如何攜帶公共的請求參數(shù)？

粗略是一個BUG

總結(jié)

威科集團CCH(R) Tagetik專家解決方案獲Nucleus“領(lǐng)先者”稱號

威科集團CCH Tagetik專家解決方案獲Nucleus“領(lǐng)先者”稱號

攜手兩大海外知名媒體美通社推出Homepage News發(fā)布服務(wù)

亞馬遜云科技助力Kyligence云上交付速度提高30% 加速國際化進程

亞馬遜云科技助力Kyligence云上交付速度提高30%

Vantage榮獲2022年ADVFN國際金融大獎亞太區(qū)最佳交易服務(wù)供應(yīng)商

Supermicro推出SuperEdge多節(jié)點解決方案，將數(shù)據(jù)中心的規(guī)模、性能和效率運用于5G、物聯(lián)網(wǎng)與智能邊緣應(yīng)用

Supermicro推出SuperEdge多節(jié)點解決方案

Lumen Edge Gateway擴展Lumen平臺以在邊緣提供IT應(yīng)用程序與虛擬化服務(wù)

The Orangeblowfish以全新形象慶祝10周年

亞馬遜首席技術(shù)官Werner Vogels：2022年及未來五大技術(shù)趨勢預(yù)測

Fingerpaint收購Engage

Adapdix推出EdgeOps(TM)混合云平臺

Adapdix推出EdgeOps混合云平臺

極客感十足的電子胸牌?ART-Badge?V2.0開發(fā)記錄！

愛立信將以62億美元收購云通信廠商Vonage

Engineering Change Order (ECO)

Understanding CMOS Image Sensor(一)

Understanding CMOS Image Sensor(二)

SystemVerilog Package的一些編碼規(guī)范

Swagger3.0?天天刷屏，真的香嗎？

目錄

前言

官方文檔如何說？

Spring Boot版本說明

添加依賴

springfox-boot-starter做了什么？

擼起袖子就是干？

定制一個基本的文檔示例

文檔如何分組？

如何添加授權(quán)信息？

如何攜帶公共的請求參數(shù)？

粗略是一個BUG

總結(jié)

Swagger3.0?天天刷屏，真的香嗎？

官方文檔如何說？

springfox-boot-starter做了什么？

擼起袖子就是干？

如何添加授權(quán)信息？

如何攜帶公共的請求參數(shù)？