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

認識界上最流行的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", "792228573@qq.com");
       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，節省運行內存。