亚洲第六页,五月丁香综合激情,操逼精品视频,色色射,黄色视频在线免费观看高清视频,69视频在线播放,日日夜夜黄片,欧美成人精品一二三区欧美风情

這篇文章，簡單給大家聊聊項目必備的 Swagger 該怎么玩。

何為 Swagger ？ 簡單來說，Swagger 就是一套基于 OpenAPI 規(guī)范構建的開源工具，可以幫助我們設計、構建、記錄以及使用 Rest API。

為何要用 Swagger ? 前后端分離的情況下，一份 Rest API 文檔將會極大的提高我們的工作效率。前端小伙伴只需要對照著 Rest API 文檔就可以搞清楚一個接口需要的參數(shù)以及返回值。通過 Swagger 我們只需要少量注解即可生成一份自帶 UI 界面的 Rest API 文檔，不需要我們后端手動編寫。并且，通過 UI 界面，我們還可以直接對相應的 API 進行調(diào)試,省去了準備復雜的調(diào)用參數(shù)的過程。

這篇文章的主要內(nèi)容：

SpringBoot 項目中如何使用？
Spring Security 項目中如何使用？
使用 knife4j 增強 Swagger

以下演示所用代碼，你可以在這個倉庫找到：https://github.com/Snailclimb/spring-security-jwt-guide （從零入門！Spring Security With JWT（含權限驗證）后端部分代碼）

SpringBoot 項目中如何使用？

Swagger3.0 官方已經(jīng)有了自己的 Spring Boot Starter，只需要添加一個 jar 包即可（SpringBoot 版本 2.3.6.RELEASE）。。


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

什么都不用配置！直接在瀏覽器中訪問 :http://ip:port/swagger-ui/ 即可。

Spring Security 項目中如何使用？

如果你的項目使用了 Spring Security 做權限認證的話，你需要為 Swagger 相關 url 添加白名單。

????String[]?SWAGGER_WHITELIST?=?{
????????????"/swagger-ui.html",
????????????"/swagger-ui/*",
????????????"/swagger-resources/**",
????????????"/v2/api-docs",
????????????"/v3/api-docs",
????????????"/webjars/**"
????};

????@Override
????protected?void?configure(HttpSecurity?http)?throws?Exception?{
????????http.cors().and()
????????????????//?禁用?CSRF
????????????????.csrf().disable()
????????????????.authorizeRequests()
????????????????//?swagger
????????????????.antMatchers(SWAGGER_WHITELIST).permitAll()
??????????......
????}

另外，某些請求需要認證之后才可以訪問，為此，我們需要對 Swagger 做一些簡單的配置。

配置的方式非常簡單，我提供兩種不同的方式給小伙伴們。

登錄后自動為請求添加 token。
為請求的 Header 添加一個認證參數(shù)，每次請求的時候，我們需要手動輸入 token。

登錄后自動為請求添加 token

通過這種方式我們只需要授權一次即可使用所有需要授權的接口。

/**
?*?@author?shuang.kou
?*?@description?swagger?相關配置
?*/
@Configuration
public?class?SwaggerConfig?{

????@Bean
????public?Docket?createRestApi()?{
????????return?new?Docket(DocumentationType.SWAGGER_2)
????????????????.apiInfo(apiInfo())
????????????????.select()
????????????????.apis(RequestHandlerSelectors.basePackage("github.javaguide.springsecurityjwtguide"))
????????????????.paths(PathSelectors.any())
????????????????.build()
????????????????.securityContexts(securityContext())
????????????????.securitySchemes(securitySchemes());
????}

????private?List?securitySchemes()?{
????????return?Collections.singletonList(new?ApiKey("JWT",?SecurityConstants.TOKEN_HEADER,?"header"));
????}

????private?List?securityContext()?{
????????SecurityContext?securityContext?=?SecurityContext.builder()
????????????????.securityReferences(defaultAuth())
????????????????.build();
????????return?Collections.singletonList(securityContext);
????}

????List?defaultAuth()?{
????????AuthorizationScope?authorizationScope
????????????????=?new?AuthorizationScope("global",?"accessEverything");
????????AuthorizationScope[]?authorizationScopes?=?new?AuthorizationScope[1];
????????authorizationScopes[0]?=?authorizationScope;
????????return?Collections.singletonList(new?SecurityReference("JWT",?authorizationScopes));
????}

????private?ApiInfo?apiInfo()?{
????????return?new?ApiInfoBuilder()
????????????????.title("Spring?Security?JWT?Guide")
????????????????.build();
????}
}

未登錄前：

登錄后：

為請求的 Header 添加一個認證參數(shù)

每次請求的時候，我們需要手動輸入 token 到指定位置。

@Configuration
public?class?SwaggerConfig?{

????@Bean
????public?Docket?createRestApi()?{
????????return?new?Docket(DocumentationType.SWAGGER_2)
????????????????.apiInfo(apiInfo())
????????????????.select()
????????????????.apis(RequestHandlerSelectors.basePackage("github.javaguide.springsecurityjwtguide"))
????????????????.paths(PathSelectors.any())
????????????????.build()
????????????????.globalRequestParameters(authorizationParameter())
????????????????.securitySchemes(securitySchemes());
????}

????private?List?securitySchemes()?{
????????return?Collections.singletonList(new?ApiKey("JWT",?SecurityConstants.TOKEN_HEADER,?"header"));
????}

????private?List?authorizationParameter()?{
????????RequestParameterBuilder?tokenBuilder?=?new?RequestParameterBuilder();
????????tokenBuilder
????????????????.name("Authorization")
????????????????.description("JWT")
????????????????.required(false)
????????????????.in("header")
????????????????.accepts(Collections.singleton(MediaType.APPLICATION_JSON))
????????????????.build();
????????return?Collections.singletonList(tokenBuilder.build());
????}

????private?ApiInfo?apiInfo()?{
????????return?new?ApiInfoBuilder()
????????????????.title("Spring?Security?JWT?Guide")
????????????????.build();
????}
}

使用 knife4j 增強 Swagger

Swagger 原生提供的界面使用體驗比較差。常用的增強 Swagger 的方案有下面兩種：

YApi?：YApi 是一個可本地部署的、打通前后端及 QA 的、可視化的接口管理平臺?？梢詭椭覀冏?swagger 頁面的體驗更加友好，目前很多大公司都在使用這個開源工具。項目地址：https://github.com/YMFE/yapi?。使用方法：當 Swagger 遇上 YApi，瞬間高大上了！
Knife4j?：Swagger 生成 Api 文檔的增強解決方案，前身是 swagger-bootstrap-ui 。官方文檔：https://xiaoym.gitee.io/knife4j/documentation/ 。

根據(jù)官網(wǎng)介紹，knife4j 是為 Java MVC 框架集成 Swagger 生成 Api 文檔的增強解決方案。

項目地址：https://gitee.com/xiaoym/knife4j 。

使用方式非常簡單,添加到相關依賴即可（SpringBoot 版本 2.3.6.RELEASE）。

<dependency>
????<groupId>com.github.xiaoymingroupId>
????<artifactId>knife4j-spring-boot-starterartifactId>
????<version>3.0.2version>
dependency>

完成之后，訪問：http://ip:port/doc.html 即可。

效果如下。可以看出，相比于 swagger 原生 ui 確實好看實用了很多。

除了 UI 上的增強之外，knife4j 還提供了一些開箱即用的功能。

比如：搜索 API 接口 （knife4j 版本>2.0.1 ）

再比如：導出離線文檔

通過 Knife4j 我們可以非常方便地導出 Swagger 文檔，并且支持多種格式。

markdown：導出當前邏輯分組下所有接口的 Markdown 格式的文檔
Html：導出當前邏輯分組下所有接口的 Html 格式的文檔
Word:導出當前邏輯分組下所有接口的 Word 格式的文檔(自 2.0.5 版本開始)
OpenAPI:導出當前邏輯分組下的原始 OpenAPI 的規(guī)范 json 結(jié)構(自 2.0.6 版本開始)
PDF:未實現(xiàn)

以 HTML 格式導出的效果圖如下。