前言html
Spring Boot 框架是目前很是流行的微服務框架,咱們不少狀況下使用它來提供 Rest API。而對於 Rest API 來講很重要的一部份內容就是文檔,Swagger 爲咱們提供了一套經過代碼和註解自動生成文檔的方法,這一點對於保證 API 文檔的及時性將有很大的幫助。本文將使用 Swagger 2 規範的 Springfox 實現來了解如何在 Spring Boot 項目中使用 Swagger,主要包含了如何使用 Swagger 自動生成文檔、使用 Swagger 文檔以及 Swagger 相關的一些高級配置和註解。前端
Swagger 簡介java
Swagger 是一套基於 OpenAPI 規範構建的開源工具,能夠幫助咱們設計、構建、記錄以及使用 Rest API。Swagger 主要包含了如下三個部分:web
Swagger Editor:基於瀏覽器的編輯器,咱們可使用它編寫咱們 OpenAPI 規範。spring
Swagger UI:它會將咱們編寫的 OpenAPI 規範呈現爲交互式的 API 文檔,後文我將使用瀏覽器來查看而且操做咱們的 Rest API。apache
Swagger Codegen:它能夠經過爲 OpenAPI(之前稱爲 Swagger)規範定義的任何 API 生成服務器存根和客戶端 SDK 來簡化構建過程。後端
爲何要使用 Swaggerapi
當下不少公司都採起先後端分離的開發模式,前端和後端的工做由不一樣的工程師完成。在這種開發模式下,維持一份及時更新且完整的 Rest API 文檔將會極大的提升咱們的工做效率。傳統意義上的文檔都是後端開發人員手動編寫的,相信你們也都知道這種方式很難保證文檔的及時性,這種文檔長此以往也就會失去其參考意義,反而還會加大咱們的溝通成本。而 Swagger 給咱們提供了一個全新的維護 API 文檔的方式,下面咱們就來了解一下它的優勢:瀏覽器
代碼變,文檔變。只須要少許的註解,Swagger 就能夠根據代碼自動生成 API 文檔,很好的保證了文檔的時效性。安全
跨語言性,支持 40 多種語言。
Swagger UI 呈現出來的是一份可交互式的 API 文檔,咱們能夠直接在文檔頁面嘗試 API 的調用,省去了準備複雜的調用參數的過程。
還能夠將文檔規範導入相關的工具(例如 SoapUI), 這些工具將會爲咱們自動地建立自動化測試。
以上這些優勢足以說明咱們爲何要使用 Swagger 了,您是否已經對 Swagger 產生了濃厚的興趣了呢?下面咱們就將一步一步地在 Spring Boot 項目中集成和使用 Swagger,讓咱們從準備一個 Spring Boot 的 Web 項目開始吧。
SpringBoot整合Swagger2
首先建立一個基礎的SpringBoot web項目。您能夠經過 Spring Initializr 頁面生成一個空的 Spring Boot 項目,或者經過idea建立一個SpringBoot項目
添加依賴
<dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> </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>
java中Swagger2配置-直接上配置代碼,Swagger2的配置是比較容易的,在成功項目建立以後,只須要開發者本身提供一個Docket的Bean。(註釋寫的很清楚,這裏就不一一解釋了。不懂的地方能夠在片尾關注我公衆號加我WX。)
/** * 集成swagger2 解決先後端分離 弊端:不能及時協商+今早解決的問題 * 使用swagger總結: * 經過swagger 給一些比基奧難理解的接口或屬性,增長註釋信息 * 接口文檔實時更新 * 能夠在線測試 * 安全問題: * 正式上線的時候 記得關閉swagger */ @Configuration//加載到springboot配置裏面 @EnableSwagger2//開啓swagger2 public class SwaggerConfig { /** * 配置swagger2 * 註冊一個bean屬性 * swagger2其實就是從新寫一個構造器,由於他沒有get set方法\ * enable() 是否啓用swagger false swagger不能再瀏覽器中訪問 * groupName()配置api文檔的分組 那就註冊多個Docket實例 至關於多個分組 * @return */ @Bean public Docket docket() { return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()) .groupName("XXX")//組名稱 .enable(true) .select() /** * RequestHandlerSelectors配置掃描接口的方式 * basePackage 配置要掃描的包 * any 掃描所有 * none 不掃描 * withClassAnnotation 掃描類上的註解 * withMethodAnnotation 掃描方法上的註解 */ .apis(RequestHandlerSelectors.basePackage("com.tinygray.madison.controller")) /** * paths() 掃描過濾方式 * any過濾所有 * none不過濾 * regex正則過濾 * ant過濾指定路徑 */ // .paths(PathSelectors.ant("/login/**")) .build(); } /** * 配置swagger2信息 =apiInfo * @return */ public ApiInfo apiInfo(){ /*做者信息*/ // Contact contact = new Contact("XXX", "http://baidu.com", "email"); Contact contact = new Contact("", "", ""); return new ApiInfo( "XXX的API接口", "company接口", "V1.0", "urn:toVs", contact, "Apache 2.0", "http://www.apache.org/licenses/LICENSE-2.0", new ArrayList()); } }
@Api(tags = "TestController測試") @RestController public class TestController { @ApiOperation("login api") @GetMapping("/") public String login() { return "Hello login ~"; } @ApiOperation("helloWord Api") @GetMapping("/index") public String index() { return "Hello World ~"; } @ApiOperation("admin Api") @GetMapping("/admin/hello") public String admin() { return "hello admin!"; } @ApiOperation("user Api") @GetMapping("/user/hello") public String user() { return "hello user"; } }
這篇文章是否幫助到你呢?掃描關注公衆號--【Madison龍少】,【Madison龍少】公衆號天天提供java乾貨,乾貨滿滿。