認識界上最流行的Api框架——swagger

swagger簡介

swagger是支持多種編程語言的Api框架。可以直接運行，在線測試API接口。有RestFul Api文檔在線自動生成工具，並且能夠達到Api文檔與API定義同步更新。

由於前端和后端分離式開發的廣泛應用，許多前端人員無法做到問題處理同步，為了提高問題的處理效率，以及避免工作中前后端工作人員的矛盾，就需要‘即時協商，目標同步’。對於這個問題，最早的解決方法是使用：指定schema並實時更新最新API、word計划文檔、后端提供接口，前端用postman測試后端接口三種方法。但是這幾種方法並不能達到即時的效果，所以swagger就應時而生。

作為世界上最流行的API框架，swagger在項目中使用時需要springfox（swagger2和swagger-ui）。這就需要在項目中導入以下兩個依賴：

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>
<!-- 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>

用SpringBoot集成swagger

1. 新建SpringBoot web項目

2. 導入swagger2和swagger-ui依賴

3. 編寫一個hello工程用於測試

4. 配置swagger，編寫config

   @Configuration
   @EnableSwagger2        //開啟Swagger2
   public class SwaggerConfig {
   }
   

5. 運行測試：http://localhost:8080/swagger-ui.html

配置swagger信息

1. swagger的bean實例docket：

   @Bean
   public Docket docket(){
       return new Docket(DocumentationType.SWAGGER_2);
   }
   

2. 配置swagger的信息：

   //配置Swagger信息=apiInfo
   private ApiInfo apiInfo(){
       //作者信息
       Contact contact = new Contact("啊俠", "https://blog.csdn.net/weixin_44821160", "[e-mail]");
       return new ApiInfo(
           "啊俠的SwaggerAPI測試文檔",
           "不要因為任何事情忘記自己最初的動力",
           "v1.0",
           "https://blog.csdn.net/weixin_44821160",
           contact,
           "Apache 2.0",
           "http://www.apache.org/licenses/LICENSE-2.0",
           new ArrayList()
       );
   }
   

swagger配置掃描接口

Docket.select()

//配置了Swagger的Docket的bean實例
    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                //RequestHandlerSelectors，配置要掃描接口的方式
                //basePackage:指定要掃描的包
                //any():掃描全部
                //none():不掃描
                //withClassAnnotation：掃描類上的注解，參數是一個注解的反射對象
                //withMethodAnnotation：掃描方法上的注解
                .apis(RequestHandlerSelectors.basePackage("com.david.swagger.controller"))
                //paths()。過濾什么路徑
                .paths(PathSelectors.ant("/david/**"))
                .build();
    }

配置是否啟動Swagger

@Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .enable(false)//enable是否啟動Swagger，如果為False，則Swagger不能再瀏覽器中訪問
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.david.swagger.controller"))
                .build();
    }

如果只希望我的Swagger在生產環境中使用，在發布的時候不使用就需要：

1. 判斷是不是生產環境 flag = false
2. 注入enable（flag）

//配置了Swagger的Docket的bean實例
    @Bean
    public Docket docket(Environment environment){

        //設置要顯示的Swagger環境
        Profiles profiles = Profiles.of("dev","test");
        //通過environment.acceptsProfiles判斷是否處在自己設定的環境當中
        boolean flag = environment.acceptsProfiles(profiles);
        System.out.println(flag);
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .enable(flag)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.david.swagger.controller"))
                .build();
    }

配置Api文檔的分組

1. .groupName（“david”）

2. 配置多個分組，多個docket實例

   @Bean
   public Docket docket1(){
       return new Docket(DocumentationType.SWAGGER_2).groupName("豪俠");
   }
   @Bean
   public Docket docket2(){
       return new Docket(DocumentationType.SWAGGER_2).groupName("真真");
   }
   @Bean
   public Docket docket3(){
       return new Docket(DocumentationType.SWAGGER_2).groupName("超強");
   }
   

3. 配置實體類

   package com.david.swagger.pojo;
   
   import io.swagger.annotations.Api;
   import io.swagger.annotations.ApiModel;
   import io.swagger.annotations.ApiModelProperty;
   
   //@Api(注釋)
   @ApiModel("用戶實體類")
   public class User {
       @ApiModelProperty("用戶名")
       public String username;
       @ApiModelProperty("密碼")
       public String password;
   
   }
   

4. 編寫controller

   package com.david.swagger.controller;
   
   import com.david.swagger.pojo.User;
   import io.swagger.annotations.Api;
   import io.swagger.annotations.ApiOperation;
   import io.swagger.annotations.ApiParam;
   import org.springframework.web.bind.annotation.GetMapping;
   import org.springframework.web.bind.annotation.PostMapping;
   import org.springframework.web.bind.annotation.RequestMapping;
   import org.springframework.web.bind.annotation.RestController;
   
   @RestController
   public class HelloController {
   
       @GetMapping(value = "/hello")
       public String hello(){
           return "hello";
       }
   
       //只要我們的接口中，返回值中存在實體類，他就會被掃描到Swagger中
       @PostMapping(value = "/user")
       public User user(){
           return new User();
       }
   
       //Operation接口,不是放在類上的，是方法
       @ApiOperation("Hello控制類")
       @GetMapping(value = "/hello2")
       public String hello2(@ApiParam("用戶名") String username){
           return "hello"+username;
       }
   
       @ApiOperation("Post測試類")
       @PostMapping(value = "/posttest")
       public User posttest(@ApiParam("用戶名") User user){
           int i = 5/0;//；模擬代碼錯誤
           return user;
       }
   }
   

總結swagger的作用

通過Swagger可以給一些比較難理解的屬性或者接口，增加注釋信息。可以達到文檔實時更新的效果，在線測試也方便理解api。swagger雖然是一個優秀的工具，但是出於安全考慮在正式發布之前關閉swagger，節省運行內存。