2023-2-1 前端達人
作為后端開放人員，最煩的事就是自己寫接口文檔和別人沒有寫接口文檔，不管是前端還是后端開發，多多少少都會被接口文檔所折磨，前端會抱怨后端沒有及時更新接口文檔，而后端又會覺得編寫接口文檔太過麻煩。Swagger 可以較好的接口接口文檔的交互問題，以一套標準的規范定義接口以及相關的信息，就能做到生成各種格式的接口文檔，生成多種語言和客戶端和服務端的代碼，以及在線接口調試頁面等等。只需要更新 Swagger 描述文件，就能自動生成接口文檔，做到前端、后端聯調接口文檔的及時性和便利性。
Swagger 是一個規范且完整的框架，用于生成、描述、調用和可視化 RESTful 風格的 Web 服務。
Swagger 的目標是對 REST API 定義一個標準且和語言無關的接口，可以讓人和計算機擁有無須訪問源碼、文檔或網絡流量監測就可以發現和理解服務的能力。當通過 Swagger 進行正確定義，用戶可以理解遠程服務并使用最少實現邏輯與遠程服務進行交互。與為底層編程所實現的接口類似，Swagger 消除了調用服務時可能會有的猜測。
Swagger 的優勢
通過在項目中引入 Springfox，可以掃描相關的代碼，生成該描述文件，進而生成與代碼一致的接口文檔和客戶端代碼。
<!-- swagger --> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-spring-web</artifactId> <version>2.9.2</version> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.9.2</version> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.9.2</version> </dependency>
在配置文件 config 目錄下，添加 swagger 的配置文件 SwaggerConfig.java
@Configuration // 配置類 @EnableSwagger2 // 開啟 swagger2 的自動配置 public class SwaggerConfig { }
這個時候 Swagger 已經算是整合到項目之中了，可以啟動下服務，輸入：http://localhost:8080/swagger-ui.html# （這里我的項目端口是 8868 ，項目路徑是 /mike，所以我打開的文檔地址為 http://localhost:8868/mike/swagger-ui.html# ）即可查看 swagger 文檔。
可以看到 Swagger 文檔中大概有這四類信息
Swagger 有自己的實例 Docket，如果我們想要自定義基本信息，可以使用 docket 來配置 swagger 的基本信息，基本信息的設置在 ApiInfo 這個對象中。
Swagger 默認的基本信息展示
ApiInfo 中默認的基本設置
SwaggerConfig.java 配置文件添加以下內容：
@Bean public Docket docket() { // 創建一個 swagger 的 bean 實例 return new Docket(DocumentationType.SWAGGER_2) // 配置基本信息 .apiInfo(apiInfo()) ; } // 基本信息設置 private ApiInfo apiInfo() { Contact contact = new Contact( "米大傻", // 作者姓名 "https://blog.csdn.net/xhmico?type=blog", // 作者網址 "777777777@163.com"); // 作者郵箱 return new ApiInfoBuilder() .title("多加辣-接口文檔") // 標題 .description("眾里尋他千百度，慕然回首那人卻在燈火闌珊處") // 描述 .termsOfServiceUrl("https://www.baidu.com") // 跳轉連接 .version("1.0") // 版本 .license("Swagger-的使用(詳細教程)") .licenseUrl("https://blog.csdn.net/xhmico/article/details/125353535") .contact(contact) .build(); }
重啟服務，打開 Swagger 文檔，基本信息改變如下所示：
默認情況下，Swagger 是會展示所有的接口信息的，包括最基礎的 basic-error 相關的接口
有時候我們希望不要展示 basic-error-controller 相關的接口，或者是說這想要顯示某些接口，比如說：user-controller 下的接口，由該怎么去實現呢？這個時候就需要設置 掃描接口
@Bean public Docket docket() { // 創建一個 swagger 的 bean 實例 return new Docket(DocumentationType.SWAGGER_2) // 配置接口信息 .select() // 設置掃描接口 // 配置如何掃描接口 .apis(RequestHandlerSelectors //.any() // 掃描全部的接口，默認 //.none() // 全部不掃描 .basePackage("com.duojiala.mikeboot.controller") // 掃描指定包下的接口，最為常用 //.withClassAnnotation(RestController.class) // 掃描帶有指定注解的類下所有接口 //.withMethodAnnotation(PostMapping.class) // 掃描帶有只當注解的方法接口 ) .paths(PathSelectors .any() // 滿足條件的路徑，該斷言總為true //.none() // 不滿足條件的路徑，該斷言總為false（可用于生成環境屏蔽 swagger） //.ant("/user/**") // 滿足字符串表達式路徑 //.regex("") // 符合正則的路徑 ) .build(); }
可根據自己的需求去設置對應的配置，這里我就不再一一贅述了，以上是我所設置的配置，重啟服務，打開 Swagger 文檔，接口信息改變如下所示：
可以看到之前 basic-error-controller 相關的接口已經沒有了
Swagger 默認只有一個 default 分組選項，如果沒有設置，所有的接口都會顯示在 default `分組下，如果功能模塊和接口數量一多，就會顯得比較凌亂，不方便查找和使用。
swagger 文檔中組名默認是 default，可通過 .groupName(String )
@Bean public Docket docket() { // 創建一個 swagger 的 bean 實例 return new Docket(DocumentationType.SWAGGER_2) .groupName("mike") // 修改組名為 "mike" ; }
修改后：
如果需要配置多個組的話，就需要配置多個 docket() 方法，這里我就簡單寫兩組，代碼如下：
/** * 展示 controller 包下所有的接口 */ @Bean public Docket docket1() { // 創建一個 swagger 的 bean 實例 return new Docket(DocumentationType.SWAGGER_2) .groupName("mike") // 修改組名為 "mike" // 配置接口信息 .select() // 設置掃描接口 // 配置如何掃描接口 .apis(RequestHandlerSelectors .basePackage("com.duojiala.mikeboot.controller") // 掃描指定包下的接口，最為常用 ) .paths(PathSelectors .any() // 滿足條件的路徑，該斷言總為true ) .build(); } /** * 展示路徑為 /error 的所有接口（基礎接口） */ @Bean public Docket docket2() { // 創建一個 swagger 的 bean 實例 return new Docket(DocumentationType.SWAGGER_2) .groupName("yank") // 修改組名為 "yank" // 配置接口信息 .select() // 設置掃描接口 // 配置如何掃描接口 .apis(RequestHandlerSelectors .any() // 掃描全部的接口，默認 ) .paths(PathSelectors .ant("/error") // 滿足字符串表達式路徑 ) .build(); }
重啟服務，打開 Swagger 文檔，接口信息改變如下所示：
組名為 mike 的文檔中只有 user-controller 相關的接口信息
組名為 yank 的文檔中只有 basic-error-controller 相關的接口信息
在開發或者測試環境下，我們開啟 swagger 會方便前端和后端的交互，但是如果在生產環境下也開啟 swagger 的話，是會將接口暴露出去的，有極大風險，如何讓 swagger 根據不同的環境來決定是否開啟？
這里我準備了四個項目的配置文件，dev、test、pro 三個環境的配置文件僅是端口上的不同
application.yml 內容如下，用于指定選擇的環境：
spring: profiles: active: dev
可以通過代碼判斷此時是在什么環境：dev、test、pro，如果是在 pro 生產環境，則關閉 swagger。
/** * swagger 配置 * @param environment 環境 */ @Bean public Docket docket(Environment environment) { // 設置環境范圍 Profiles profiles = Profiles.of("dev","test"); // 如果在該環境返回內則返回：true，反之返回 false boolean flag = environment.acceptsProfiles(profiles); // 創建一個 swagger 的 bean 實例 return new Docket(DocumentationType.SWAGGER_2) .enable(flag) // 是否開啟 swagger：true -> 開啟，false -> 關閉 ; }
在 application.yml 全局配置文件中環境指向 dev 時，是可以打開 swagger 的
如果我將 application.yml 全局配置文件中環境指向 pro 時，就不能打開 swagger 了，提示 Could not render e, see the console
之前有說 Swagger 會將接口請求或者相應的實體類信息展示在 Models 下的，比如我 UserController.java 下有一個接口如下所示：
@PostMapping(value = "/query-user-info") public ResponseBean queryUserInfo(@RequestBody @Validated IdReq req) { return ResponseBean.success(userService.queryUserInfo(req)); }
它的請求體是 IdReq，響應是 ResponseBean，Models 展示這兩個實體類信息如下：
前端可通過看這個 Models 知道后端定義實體類的信息。
該注解是作用于類上面的，是用來描述類的一些基本信息的。
相關屬性：
value：提供類的一個備用名，如果不設置，默認情況下將使用 class 類的名稱
譬如：這個為給 IdReq 這個類添加該注解
@Data @NoArgsConstructor @AllArgsConstructor @ApiModel(value = "Id請求體") public class IdReq { private String id; }
可以看到這里的名字從 IdReq 變成 Id請求體 了
它的作用是添加和操作屬性模塊的數據。
該注解的使用詳情可參見博客：@ApiModelProperty注解的用法
這里我還是以 IdReq 類為例，為該類的屬性添加說明
@Data @NoArgsConstructor @AllArgsConstructor @ApiModel(value = "Id請求體") public class IdReq { @ApiModelProperty("主鍵id") private String id; }
可以看到這里對該字段有一個備注說明。
該注解用來對某個方法/接口進行描述
該注解的使用詳情可參見博客：Swagger @ApiOperation 注解詳解
這里我以 UserController 下的接口為例：
@PostMapping(value = "/query-user-info") @ApiOperation(value = "根據id查詢用戶詳情") public ResponseBean queryUserInfo(@RequestBody @Validated IdReq req) { return ResponseBean.success(userService.queryUserInfo(req)); }
可以看見該接口就多了對其的描述信息。
該注解使用在方法上或者參數上，字段說明，表示對參數的添加元數據（說明或者是否必填等）
相關屬性：
這里我以 UserController 下的接口為例：
@PostMapping(value = "/query-user-infos") @ApiOperation(value = "條件查詢用戶信息") public ResponseBean queryUserInfos( // name 用戶名稱 不必填 @ApiParam(value = "用戶名稱", required = false) @RequestParam(required = false) String name, // gender 用戶性別 必填 @ApiParam(value = "用戶性別", required = true) @RequestParam(required = true) GenderEnum gender ) { return ResponseBean.success(userService.queryUserInfos(name,gender)); }
這里會展示請求參數的備注信息，以及是否必填等。
使用 swagger 除了讓前后端交互變得方便，也讓接口的請求變得簡單，只需要填寫好請求所需要的參數信息，便可直接發起請求。
比如說接口 /user/query-user-info
點擊 Try it out
設置好請求所需的參數，點擊 Execute 執行
就能看到接口響應的結果了
接口 /user/query-user-infos 也差不多
有時候我們的接口是需要獲取請求頭信息的，這樣的話就還需要在 swagger 配置中添加請求頭的配置。
@Bean public Docket docket() { // 設置請求頭 List<Parameter> parameters = new ArrayList<>(); parameters.add(new ParameterBuilder() .name("token") // 字段名 .description("token") // 描述 .modelRef(new ModelRef("string")) // 數據類型 .parameterType("header") // 參數類型 .defaultValue("default value") // 默認值：可自己設置 .hidden(true) // 是否隱藏 .required(false) // 是否必須 .build()); // 創建一個 swagger 的 bean 實例 return new Docket(DocumentationType.SWAGGER_2) .groupName("mike") // 修改組名為 "mike" // 配置接口信息 .select() // 設置掃描接口 // 配置如何掃描接口 .apis(RequestHandlerSelectors .basePackage("com.duojiala.mikeboot.controller") // 掃描指定包下的接口，最為常用 ) .paths(PathSelectors .any() // 滿足條件的路徑，該斷言總為true ) .build() // 添加請求頭參數 .globalOperationParameters(parameters); }
比如接口：
@GetMapping(value = "/get-token") @ApiOperation(value = "獲取請求頭中的token信息") public void getToken( @RequestHeader(value = "token",required = false) String token ) { // 直接獲取 token 信息 System.out.println("token = " + token); // 通過代碼獲取 ServletRequestAttributes servletRequestAttributes = (ServletRequestAttributes) RequestContextHolder.getRequestAttributes(); if (servletRequestAttributes != null) { HttpServletRequest request = servletRequestAttributes.getRequest(); String header = request.getHeader("token"); System.err.println("header = " + header); } }
可以看到這個接口已經可以去設置請求頭了，調用接口
后端也能獲取到。
分享此文一切功德，皆悉回向給文章原作者及眾讀者.
免責聲明：藍藍設計尊重原作者，文章的版權歸原作者。如涉及版權問題，請及時與我們取得聯系，我們立即更正或刪除。
藍藍設計( www.syprn.cn )是一家專注而深入的界面設計公司，為期望卓越的國內外企業提供卓越的UI界面設計、BS界面設計 、 cs界面設計 、 ipad界面設計 、 包裝設計 、 圖標定制 、 用戶體驗 、交互設計、 網站建設 、平面設計服務、UI設計公司、界面設計公司、UI設計服務公司、數據可視化設計公司、UI交互設計公司、高端網站設計公司、UI咨詢、用戶體驗公司、軟件界面設計公司
藍藍設計的小編 http://www.syprn.cn