Swagger簡介

前后端分離

最常見的：Vue + SpringBoot

前后端分離，后臺負責寫接口。隨著接口越來越多，隨時改變接口的可能性也很大，大家爭吵是很正常的。

解決方案

• 先指定計劃提綱，事實更新API，降低集成風險

• 傳統是需要自己去維護一個doc的文檔或者公司統一放在一個接口清單的web服務上。每次開發者需要單獨添加上去。修改后還需要維護。

• 前后端分離：

• 前端測試后端接口：postman，就為了測一個接口還要下載第三方軟件，太奢侈了

• 后端提供接口，實時更新消息及變動

現接入swagger，通過簡單的注解即可生成文檔，并且隨著接口變化自動會變化。統一管理方便快捷

Swagger

• 號稱最流行的API框架

• RestFul Api 文檔在線自動生產，Api文檔與定義同步更新

• 直接運行，可以在線測試接口

• 支持多種語言（java、php等）

官網：https://swagger.io/

SpringBoot集成Swagger

1.新建SpringBoot項目
2.導入依賴

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

3.隨便寫一個controller接口，比如 hello
4.配置swagger2，swagger2 是新版的，和swagger 是不一樣的哦！

/**
 * @author : aBiu---
 *
 * create at:  2019-12-20  16:20
 *
 * description: api接口配置
 */@Configuration@EnableSwagger2     // 開啟public class SwaggerConfig {  private ApiInfo apiInfo() {    return new ApiInfoBuilder().title("API接口文檔") //頁面標題
        .description("接口管理")//詳細描述
        .version("1.0.0") //版本號
        .build();
  }  @Bean
  public Docket createRestApi() {    return new Docket(DocumentationType.SWAGGER_2)
        .apiInfo(apiInfo())     // 需要上面定義的ApiInfo，信息顯示到頁面上
        .groupName("aBiu")      // 分組，如果想搞多個分組，就寫多個Docket 的示例就行了
        .select()
        .apis(RequestHandlerSelectors.basePackage("com.*")) //這里寫的是API接口所在的包位置，也可以設置其他掃描方式
        .paths(PathSelectors.any())     // 過濾，有好幾種方式可以設置
        .build();
  }
}

5.測試運行，然后訪問：http://localhost:8080/swagger-ui.html 或 http://localhost:8080/swagger-ui/index.html

由于版本的不同，可能名字不一樣，具體可以到jar包里去看一下就好了

Swagger注解

@Api：　　　　　　　　　　修飾類，一般來描述Controller的@ApiOperation：　　　　 描述類的 方法 或者 接口@ApiParam：　　　　　　　單個參數描述@ApiModel：　　　　　　　用在實體類上面@ApiProperty：　　　　　實體類里面的屬性@ApiImplicitParam：      用在 @ApiImplicitParams 注解中，指定一個請求參數的配置信息               
　　　　　　　　　　　　　　　　name：參數名        
　　　　　　　　　　　　　　　　value：參數的漢字說明、解釋        
　　　　　　　　　　　　　　　　required：參數是否必須傳        
　　　　　　　　　　　　　　　　paramType：參數放在哪個地方            · 
　　　　　　　　　　　　　　　　header --> 請求參數的獲?。篅RequestHeader            · 
　　　　　　　　　　　　　　　　query --> 請求參數的獲?。篅RequestParam            · 
　　　　　　　　　　　　　　　　path（用于restful接口）--> 請求參數的獲取：@PathVariable            · 
　　　　　　　　　　　　　　　　body（不常用）            · 
　　　　　　　　　　　　　　　　form（不常用）            
　　　　　　　　　　　　　　　　dataType：參數類型，默認String，其它值dataType="Integer"               　　　　　　　　　　　　　　　　defaultValue：參數的默認值
　　　　　　　　　　　　　　　　其它若干@ApiResponse：　　　　　描述HTTP響應其中1個的描述@ApiResponses：　　　　 描述出HTTP響應整體描述@ApiClass@ApiError@ApiErrors@ApiParamImplicit@ApiParamsImplicit

示例：一個接口的說明（controller類）

/**
     * XXX 認證人員信息接口
     * @param signerType
     * @param certType
     * @param certNo
     * @param name
     * @param phoneNo
     * @param cardNo
     * @param signSupplier
     * @param authType
     * @param notifyUrl
     * @return
     */
    @ApiOperation(value = "XXX 的接口", httpMethod = "POST")
    @ApiImplicitParams({
            @ApiImplicitParam(paramType = "String", name = "signerType", dataType = "String", required = true, value = "簽署人類型:1.個人，2.企業"),
            @ApiImplicitParam(paramType = "String", name = "certType", dataType = "String", required = false, value = "證件類型:簽署人類型是個人時必填"),
            @ApiImplicitParam(paramType = "String", name = "certNo", dataType = "String", required = false, value = "簽署人類型:簽署人類型是個人時必填"),
            @ApiImplicitParam(paramType = "String", name = "name", dataType = "String", required = true, value = "姓名"),
            @ApiImplicitParam(paramType = "String", name = "phoneNo", dataType = "String", required = false, value = "手機號:簽署人類型是個人時必填"),
            @ApiImplicitParam(paramType = "String", name = "notifyUrl", dataType = "String", required = false, value = "回調地址")
    })
    @PostMapping("/signerInfo")
    public ResultInfo signerInfo(String signerType, String certType, String certNo, String name, String phoneNo, @RequestParam(required = false) String notifyUrl){        return contractService.signerInfo(signerType,certType,certNo,name,phoneNo,cardNo,signSupplier,authType,notifyUrl);
    }

項目發布上線時候，一定要記得，一定要記得，把swagger 關閉，因為你不可能讓用戶看到你的接口吧？

生成漂亮的ui界面

加入依賴

    <dependency>
        <groupId>com.github.caspar-chen</groupId>
        <artifactId>swagger-ui-layer</artifactId>
        <version>1.1.3</version>
    </dependency>

訪問地址 http://localhost:8080/docs.html

這個好像沒有分組的屬性，如果swagger配置時候加了分組，在這里會有異常