前後端分離，後臺負責寫介面。隨著介面越來越多，介面清單越來越重要，傳統是需要自己去維護一個doc的文件或者公司統一放在一個介面清單的web服務上。每次開發者需要單獨新增上去。修改後還需要維護。現接入swagger，通過簡單的註解即可生成文件，並且隨著介面變化自動會變化。統一管理方便快捷

引入jar包
配置swagger相關設定
swagger相關注解

1.通過pom檔案引入相應的jar包

        <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>

2、在程式碼中配置Swagger相關配置（SwaggerConfig）

/**
 * @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())
        .select()
        .apis(RequestHandlerSelectors.basePackage("org.*")) //這裡寫的是API介面所在的包位置

        .paths(PathSelectors.any())
        .build();
  }
}

3、常見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

4、示例：一個介面的說明（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);
    }

引數裡的那個@RequestParam(required = false) 註解不算是開發文件註解，這只是讓url 這個引數失效的作用。。。

5、訪問http://localhost:8080/view/swagger-ui.html view為專案名

6、生成漂亮的ui介面

加入依賴：

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

訪問地址http://localhost:8080/view/docs.html view為專案名

介面如下：

最後、訪問地址http://localhost:8080/view/swagger-ui.html view為專案名