問題描述?

在團隊開發中，一個好的 API 文檔不但可以減少大量的溝通成本，還可以幫助一位新人快速上手業務。傳統的做法是由開發人員創建一份 RESTful API 文檔來記錄所有的接口細節，并在程序員之間代代相傳。

這種做法存在以下幾個問題：

• API 接口眾多，細節復雜，需要考慮不同的HTTP請求類型、HTTP頭部信息、HTTP請求內容等，想要高質量的完成這份文檔需要耗費大量的精力；
• 難以維護。隨著需求的變更和項目的優化、推進，接口的細節在不斷地演變，接口描述文檔也需要同步修訂，可是文檔和代碼處于兩個不同的媒介，除非有嚴格的管理機制，否則很容易出現文檔、接口不一致的情況
• 接口測試不方便，一般只能借助第三方工具（如：Postman）來測試。

基本概念?

Swagger2?是一個開源軟件框架，從根本上解決上述問題。它作為一個規范和完整的框架，可以用于設計、生成、描述、調用和可視化 RESTful 風格的 Web 服務，使開發人員將大部分精力集中到業務中，而不是繁雜瑣碎的文檔中：

• 接口文檔在線自動生成，文檔隨接口變動實時更新，節省維護成本。
• 支持在線接口測試，不依賴第三方工具。
• 將代碼和文檔融為一體。

Maven

<dependencies>...<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui --><dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger-ui</artifactId><version>2.9.2</version></dependency> ?<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 --><dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger2</artifactId><version>2.9.2</version></dependency> </dependencies>

解決方案?

配置類?

Swagger2Configuration.java

package com.zstu.metrocity.config;import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import springfox.documentation.builders.ApiInfoBuilder; import springfox.documentation.builders.PathSelectors; import springfox.documentation.builders.RequestHandlerSelectors; import springfox.documentation.service.Contact; import springfox.documentation.spi.DocumentationType; import springfox.documentation.spring.web.plugins.Docket; import springfox.documentation.swagger2.annotations.EnableSwagger2;/*** @Author ShenTuZhiGang* @Version 1.0.0* @Date 2020-04-13 19:57* Swagger2 配置類*/ @Configuration @EnableSwagger2 public class CustomSwagger2Config {@BeanDocket docket(){return new Docket(DocumentationType.SPRING_WEB).select()//配置需要掃描的controller位置.apis(RequestHandlerSelectors.basePackage("com.zstu.controller"))//配置路徑.paths(PathSelectors.any())//構建.build()//文檔信息.apiInfo(new ApiInfoBuilder()//描述.description("MetroCity RESTful API 文檔")//聯系人信息.contact(new Contact("申屠志剛",//名字"https://shentuzhigang.blog.csdn.net/",//網址"1600337300@qq.com"))//郵箱//版本.version("V1.0")//標題.title("MetroCity RESTful API 文檔")//License.license("Apache 2.0")//License 網址.licenseUrl("http://www.apache.org/licenses/LICENSE-2.0").build());}}

Swagger2Configuration.java 配置類的內容不多，配置完成后也很少變化，簡單了解即可。

如上代碼所示，通過 @Configuration 注解，讓 Spring 加載該配置類。再通過 @EnableSwagger2 注解來啟用Swagger2。成員方法 createRestApi 函數創建 Docket 的Bean之后，apiInfo() 用來創建該 Api 的基本信息（這些基本信息會展現在文檔頁面中）。select() 函數返回一個 ApiSelectorBuilder實例用來控制哪些接口暴露給 Swagger 來展現，本例采用指定掃描的包路徑來定義，Swagger 會掃描該包下所有 Controller 定義的 API，并產生文檔內容（除了被 @ApiIgnore 指定的請求）。

API 接口編寫

在完成了上述配置后，其實已經可以產生文檔內容，但是這樣的文檔主要針對請求本身，而描述主要來源于函數等命名產生，對用戶并不友好，我們通常需要自己增加一些說明來豐富文檔內容。

@Api(description = "生產者進程API接口") @RestController @RequestMapping("/producer") public class ActiveMQProducer {private static final Logger logger = LoggerFactory.getLogger(ActiveMQConsumer.class);@Value(value = "${mq.active.count-queue-name}")private String COUNT_QUEUE_NAME;@Value(value = "${mq.active.query-queue-name}")private String QUERY_QUEUE_NAME;@Autowiredprivate ActiveMQManager mqManager;@ApiOperation(value="發送解析文本", notes="發送解析文本", produces="application/json")@RequestMapping(value="/sendText", produces={ MediaType.APPLICATION_JSON_UTF8_VALUE }, consumes={ MediaType.APPLICATION_JSON_UTF8_VALUE }, method=RequestMethod.POST)public String sendText(@RequestBody String text) {logger.info("發送的文本內容：{}", text);try {mqManager.sendMsg(COUNT_QUEUE_NAME, text);} catch (Exception e){e.printStackTrace();logger.error(e.getMessage());}return "SUCESS";}@ApiOperation(value="查詢單詞計數", notes="查詢單詞計數", produces="application/json")@ApiImplicitParam(name = "word", value = "單詞", paramType = "query", required = true, dataType = "String")@RequestMapping(value="/queryWordCount", produces={ MediaType.APPLICATION_JSON_UTF8_VALUE }, consumes={ MediaType.APPLICATION_JSON_UTF8_VALUE }, method=RequestMethod.POST)public String queryWordCount(@RequestBody String word) {logger.info("查詢單詞計數：{}", word);try {mqManager.sendMsg(QUERY_QUEUE_NAME, word);} catch (Exception e){e.printStackTrace();logger.error(e.getMessage());}return "SUCESS";} }

本接口示例了 @ApiOperation 和 @ApiImplicitParam 兩個注解的使用。

Swagger 通過注解定制接口對外展示的信息，這些信息包括接口名、請求方法、參數、返回信息等。更多注解類型：

• @Api：修飾整個類，描述Controller的作用
• @ApiOperation：描述一個類的一個方法，或者說一個接口
• @ApiParam：單個參數描述
• @ApiModel：用對象來接收參數
• @ApiProperty：用對象接收參數時，描述對象的一個字段
• @ApiResponse：HTTP響應其中1個描述
• @ApiResponses：HTTP響應整體描述
• @ApiIgnore：使用該注解忽略這個API
• @ApiError ：發生錯誤返回的信息
• @ApiImplicitParam：描述一個請求參數，可以配置參數的中文含義，還可以給參數設置默認值
• @ApiImplicitParams：描述由多個 @ApiImplicitParam 注解的參數組成的請求參數列表

啟動 SpringBoot 應用

SpringBoot 啟動成功后，訪問 http://localhost:8080/swagger-ui.html

展開類維度的接口列表，如 active-mq-producer，頁面會列出該類中定義的所有接口。點擊任意接口，可查看該接口的 url 路徑、請求類型、參數描述和返回碼說明等信息。

點擊右上角的 “Try it out！”按鈕，錄入請求信息，點擊 Execute 按鈕完成一次請求調用！

?

Spring Security 中的配置

Spring Boot 項目中如果集成了 Spring Security，在不做額外配置的情況下，Swagger2 文檔會被攔截。解決方法是在 Security 的配置類中重寫 configure 方法添加白名單即可：

@Override public void configure ( WebSecurity web) throws Exception {web.ignoring().antMatchers("/swagger-ui.html").antMatchers("/v2/**").antMatchers("/swagger-resources/**"); }

參考文章

https://www.jianshu.com/p/c79f6a14f6c9

總結

以上是生活随笔為你收集整理的Spring Boot——集成Swagger2的全部內容，希望文章能夠幫你解決所遇到的問題。

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