Swagger簡介
前后端分離
最常見的：Vue + SpringBoot
前后端分離，后台負責寫接口。隨着接口越來越多，隨時改變接口的可能性也很大，大家爭吵是很正常的。
解決方案
- 先指定計划提綱，事實更新API，降低集成風險
- 傳統是需要自己去維護一個doc的文檔或者公司統一放在一個接口清單的web服務上。每次開發者需要單獨添加上去。修改后還需要維護。
- 前后端分離：
- 前端測試后端接口：postman，就為了測一個接口還要下載第三方軟件，太奢侈了
- 后端提供接口，實時更新消息及變動
現接入swagger，通過簡單的注解即可生成文檔，並且隨着接口變化自動會變化。統一管理方便快捷
Swagger
- 號稱最流行的API框架
- RestFul Api 文檔在線自動生產，Api文檔與定義同步更新
- 直接運行，可以在線測試接口
- 支持多種語言（java、php等）
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配置時候加了分組，在這里會有異常
