SpringBoot中優雅的使用Swagger2

前言

　　Spring Boot 框架是目前很是流行的微服務框架，咱們不少狀況下使用它來提供 Rest API。而對於 Rest API 來講很重要的一部份內容就是文檔，Swagger 爲咱們提供了一套經過代碼和註解自動生成文檔的方法，這一點對於保證 API 文檔的及時性將有很大的幫助。本文將使用 Swagger 2 規範的 Springfox 實現來了解如何在 Spring Boot 項目中使用 Swagger，主要包含了如何使用 Swagger 自動生成文檔、使用 Swagger 文檔以及 Swagger 相關的一些高級配置和註解。

Swagger 簡介

Swagger 是一套基於 OpenAPI 規範構建的開源工具，能夠幫助咱們設計、構建、記錄以及使用 Rest API。Swagger 主要包含了如下三個部分：

1. Swagger Editor：基於瀏覽器的編輯器，咱們可使用它編寫咱們 OpenAPI 規範。

2. Swagger UI：它會將咱們編寫的 OpenAPI 規範呈現爲交互式的 API 文檔，後文我將使用瀏覽器來查看而且操做咱們的 Rest API。

3. Swagger Codegen：它能夠經過爲 OpenAPI（之前稱爲 Swagger）規範定義的任何 API 生成服務器存根和客戶端 SDK 來簡化構建過程。

爲何要使用 Swagger

當下不少公司都採起先後端分離的開發模式，前端和後端的工做由不一樣的工程師完成。在這種開發模式下，維持一份及時更新且完整的 Rest API 文檔將會極大的提升咱們的工做效率。傳統意義上的文檔都是後端開發人員手動編寫的，相信你們也都知道這種方式很難保證文檔的及時性，這種文檔長此以往也就會失去其參考意義，反而還會加大咱們的溝通成本。而 Swagger 給咱們提供了一個全新的維護 API 文檔的方式，下面咱們就來了解一下它的優勢：

1. 代碼變，文檔變。只須要少許的註解，Swagger 就能夠根據代碼自動生成 API 文檔，很好的保證了文檔的時效性。

2. 跨語言性，支持 40 多種語言。

3. Swagger UI 呈現出來的是一份可交互式的 API 文檔，咱們能夠直接在文檔頁面嘗試 API 的調用，省去了準備複雜的調用參數的過程。

4. 還能夠將文檔規範導入相關的工具（例如 SoapUI）, 這些工具將會爲咱們自動地建立自動化測試。

以上這些優勢足以說明咱們爲何要使用 Swagger 了，您是否已經對 Swagger 產生了濃厚的興趣了呢？下面咱們就將一步一步地在 Spring Boot 項目中集成和使用 Swagger，讓咱們從準備一個 Spring Boot 的 Web 項目開始吧。

SpringBoot整合Swagger2

1. 首先建立一個基礎的SpringBoot web項目。您能夠經過 Spring Initializr 頁面生成一個空的 Spring Boot 項目，或者經過idea建立一個SpringBoot項目

2. 添加依賴

   1. Spring Boot 的 Web 依賴　

      <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
      </dependency>

   2. 集成swagger2　

      <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger2</artifactId>
        <version>2.9.2</version>
      </dependency>

   3. 集成Swagger UI

      <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger-ui</artifactId>
        <version>2.9.2</version>
      </dependency>

3. 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());
       }
   ​
   }

    

4. 編寫一些簡單的java接口。（你能夠根據你的狀況進行編寫）

   @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";
       }
   }

5. 驗證代碼-到這裏咱們已經成功集成Swagger2，而後啓動項目，輸入http://localhost:8080/swagger-ui.html，若是能出現下面界面，說明配置成功了。
6. 未完待續。下章節講解Swagger的經常使用註解。

   這篇文章是否幫助到你呢？掃描關注公衆號--【Madison龍少】，【Madison龍少】公衆號天天提供java乾貨，乾貨滿滿。