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

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

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

這篇文章的主要內容：

SpringBoot 項目中如何使用？

Spring Security 項目中如何使用？

使用 knife4j 增強 Swagger

SpringBoot 項目中如何使用？

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

<!--?swagger?--> <dependency><groupId>io.springfox</groupId><artifactId>springfox-boot-starter</artifactId><version>3.0.0</version> </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/**"};@Overrideprotected?void?configure(HttpSecurity?http)?throws?Exception?{http.cors().and()//?禁用?CSRF.csrf().disable().authorizeRequests()//?swagger.antMatchers(SWAGGER_WHITELIST).permitAll()......}

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

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

登錄后自動為請求添加 token。

為請求的 Header 添加一個認證參數，每次請求的時候，我們需要手動輸入 token。

登錄后自動為請求添加 token

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

/***?@author?shuang.kou*?@description?swagger?相關配置*/ @Configuration public?class?SwaggerConfig?{@Beanpublic?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<SecurityScheme>?securitySchemes()?{return?Collections.singletonList(new?ApiKey("JWT",?SecurityConstants.TOKEN_HEADER,?"header"));}private?List<SecurityContext>?securityContext()?{SecurityContext?securityContext?=?SecurityContext.builder().securityReferences(defaultAuth()).build();return?Collections.singletonList(securityContext);}List<SecurityReference>?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 添加一個認證參數

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

@Configuration public?class?SwaggerConfig?{@Beanpublic?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<SecurityScheme>?securitySchemes()?{return?Collections.singletonList(new?ApiKey("JWT",?SecurityConstants.TOKEN_HEADER,?"header"));}private?List<RequestParameter>?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?。

Knife4j?：Swagger 生成 Api 文檔的增強解決方案，前身是 swagger-bootstrap-ui 。官方文檔：https://xiaoym.gitee.io/knife4j/documentation/ 。

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

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

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

<dependency><groupId>com.github.xiaoymin</groupId><artifactId>knife4j-spring-boot-starter</artifactId><version>3.0.2</version> </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 的規范 json 結構(自 2.0.6 版本開始)

• PDF:未實現

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

有道無術，術可成；有術無道，止于術

歡迎大家關注Java之道公眾號

好文章，我在看??

總結

以上是生活随笔為你收集整理的Swagger 官方 Starter 配上这个增强方案是真的香！的全部內容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網站內容還不錯，歡迎將生活随笔推薦給好友。