線上API介面文件swagger2
Swagger™的目標是為REST API 定義一個標準的,與語言無關的介面,使人和計算機在看不到原始碼或者看不到文件或者不能通過網路流量檢測的情況下能發現和理解各種服務的功能。當服務通過Swagger定義,消費者就能與遠端的服務互動通過少量的實現邏輯。
簡單說,swagger能夠根據程式碼中的註釋自動生成api文件,並且提供測試介面;
swagger和swagger2是兩個不同的版本,現在用的比較多的是swagger和springfox,springfox就是swagger-springmvc的升級版,也叫swagger2;
使用springfox;
整合springfox和springmvc://新增依賴
<!-- swagger2 start -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.7.0</version></dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.7.0</version>
</dependency>
<!-- swagger2 end -->
@Configuration
@EnableSwagger2
public class ApiConfig {
@Bean
public Docket docket() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("cn.wolfcode"))//掃描路徑
// .apis(RequestHandlerSelectors.withMethodAnnotation(ApiImplicitParams.class))//根據註解定製
.paths(PathSelectors.any()) //定義哪些路徑的介面需要生成文件
.build();
}
@Bean
public ApiInfo apiInfo() {
Contact contact = new Contact("sky","https://www.jianshu.com/u/a099a2677722","8888@126.com");
return new ApiInfoBuilder()
.title("Spring Boot中使用Swagger2構建RESTful API")//文件首頁標題
.description("swagger2-文件構建利器")//文件描述資訊
.contact(contact) //建立者資訊
.version("1.0") //文件版本
.build();
}
}
訪問地址:http://localhost:8080/v2/api-docs
ui訪問地址:http://localhost:8080/swagger-ui.html
springfox的標籤:
@Api(value = "使用者增刪改查",description = "詳細描述")
@RestController
@RequestMapping("/users")
public class EmpController {
//獲取使用者列表
@ApiOperation(value = "獲取使用者列表",notes = "獲取使用者列表詳細描述")
@GetMapping
public List<Emp> getUsers(){
List list = new ArrayList<>();
list.add(new Emp(1L,"A"));
list.add(new Emp(2L,"B"));
list.add(new Emp(3L,"C"));
return list;
}
//獲取使用者
/*
params = "pwd=999"
headers = "Content-Type=application/json" == "Accept=application/json"
headers="contentType=application/json" == consumes="application/json"
*/
@RequestMapping(value = "/{id}",method = RequestMethod.GET)
public Emp getUser(@PathVariable("id") Long id){
System.out.println("id : "+id);
return new Emp(1L,"xx");
}
//刪除使用者
@ApiImplicitParams({
@ApiImplicitParam(name = "id",value = "使用者的唯一標識",required = true),
@ApiImplicitParam(name = "name" ,value = "使用者名稱" , required = false)
})
@ApiResponses({
@ApiResponse(code = 401 ,message = "禁止訪問")
})
@DeleteMapping("/{id}/{name}")
public void deleteUsers(@PathVariable("id") Long id ,@PathVariable("name") String name){
System.out.println("刪除成功...");
}
//建立使用者
@ApiIgnore
@PostMapping
public Emp createUsers(@RequestBody Emp emp){
System.out.println(emp);
return emp;
}
}
swagger2優點: 簡單 , 實時 , 可測試 , 容易管理
swagger2缺點: 程式碼侵入性太強, 影響正常程式碼閱讀
學習swagger2就是學習怎麼使用註解為介面新增描述資訊
@Api:修飾整個類,描述Controller的作用
@ApiOperation:描述一個類的一個方法,或者說一個介面
@ApiImplicitParams:多個請求引數
@ApiImplicitParam:一個請求引數
@ApiResponses:HTTP響應整體描述
@ApiResponse:HTTP響應其中1個描述
@ApiModel:用物件來接收引數
@ApiModelProperty:用物件接收引數時,描述物件的一個欄位
@ApiIgnore:使用該註解忽略這個API
類和方法的描述:
@Api修飾整個類,描述Controller的作用
@ApiOperation 貼在方法上,描述一個方法的作用
1、@Api註解的使用:貼在類上,主要用下面的這幾個屬性
1)value:該controller簡短的標題
2)description:詳細介紹
3)producer:說明該controller是使用什麼顯示層格式的
4)protocols:使用什麼協議
2、@ApiOperation註解的使用:貼在方法上,主要用下面的這幾個屬性
1)value:該方法簡短的變態
2)note:詳細介紹
3)code:正常情況下返回的狀態碼是多少
4)httpMethod:使用什麼http方法
5)response:響應什麼物件,這裡寫的是響應的物件的位元組碼
/**
*
* @param param
* @return
*/
@ApiOperation(value = "獲取所有產品資訊", notes = "獲取所有產品資訊", httpMethod = "GET")
@ResponseBody
@RequestMapping(value="/sync/test", method = RequestMethod.GET)
public JSONMessage test(String value,String notes) {
return JSONMessage.success("測試功能");
}
引數的描述:
貼在引數上
@ApiImplicitParams 多個請求引數
@ApiImplicitParam 一個請求引數
@ApiParam 單個引數描述
1)name:引數名
2)value:引數名對應的值
3)dataType:引數的型別
4)require:該引數是否必填
5)paramType:該引數的來源型別,它的值有如下:
query:該引數從位址列問號後面的引數獲取
form:該引數從form表單中獲取
path:該引數從URL地址上獲取
body:該引數從請求體中獲取
header:該引數從請求頭獲取
響應的描述:
@ApiResponses:HTTP響應整體的描述
@ApiResponse:HTTP響應中某一種響應的描述
用在@ApiResponses中,一般用於表達一個錯誤的響應資訊(200相應不寫在這裡面)
code:數字,例如400
message:資訊,例如"請求引數沒填好"
response:丟擲的異常類
物件模型描述:
@ApiModel/@ApiModelProperty
@ApiModel:描述一個Model的資訊(這種一般用在post建立的時候,使用@RequestBody這樣的場景,請求引數無法使用@ApiImplicitParam註解進行描述的時候)
@ApiModelProperty:描述一個model的屬性
忽略介面API:
@ApiIgnore 貼了該註解的api 會被忽略,不生成介面文件
兩種不生成api的方式:
1、@ApiIgnore:可以貼在類和方法上
2、在swagger配置類上的select()方法上呼叫apis(),apis方法需要傳入一個selector。可以使用RequestHandlerSelector內建的selector
springBoot整合swagger2://新增依賴
<!-- swagger2 start -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.7.0</version></dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.7.0</version>
</dependency>
<!-- swagger2 end -->
@Configuration
@EnableSwagger2
public class SwaggerConfig{
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
// .apis(RequestHandlerSelectors.basePackage("cn.wolfcode.controller"))//掃描路徑
.apis(RequestHandlerSelectors.withMethodAnnotation(ApiImplicitParams.class))//根據註解定製
.paths(PathSelectors.any()) //定義哪些路徑的介面需要生成文件
.build();
}
@Bean
private ApiInfo apiInfo() {
Contact contact = new Contact("sky","https://www.jianshu.com/u/a099a2677722","8888@126.com");
return new ApiInfoBuilder()
.title("Spring Boot中使用Swagger2構建RESTful API")//文件首頁標題
.description("swagger2-文件構建利器")//文件描述資訊
.contact(contact) //建立者資訊
.version("1.0") //文件版本
.build();
}
}
相關文章
- 如何使用swagger2輕鬆生成線上介面文件Swagger
- springMVC整合swagger2來輸出介面文件SpringMVCSwagger
- swagger線上api文件搭建指南SwaggerAPI
- Spring boot 之自動生成API文件swagger2Spring BootAPISwagger
- eosjs 文件(API介面)JSAPI
- Spring Boot 整合 Swagger2,構建強大的 API 文件Spring BootSwaggerAPI
- SpringBoot整合Swagger2,再也不用維護介面文件了!Spring BootSwagger
- 線上生成二維碼的API介面API
- 有了Swagger2,再也不用為寫Api文件頭疼了SwaggerAPI
- 最新線上介面文件管理工具推薦
- SpringBoot3整合SpringDoc實現線上介面文件Spring Boot
- 微服務雲架構-Swagger2構建強大的RESTful API文件微服務架構SwaggerRESTAPI
- SpringBoot 實戰 (四) | 整合 Swagger2 構建強大的 RESTful API 文件Spring BootSwaggerRESTAPI
- 如何使用Swagger-UI線上生成漂亮的介面文件SwaggerUI
- ShowDoc v2.7.1 釋出,IT 團隊的線上 API 文件、技術文件工具API
- ShowDoc v2.8.7 釋出,IT 團隊的線上 API 文件、技術文件工具API
- ShowDoc v2.9.14 釋出,IT 團隊的線上 API 文件、技術文件工具API
- ShowDoc v2.10.0 釋出, IT 團隊的線上 API 文件、技術文件工具API
- ShowDoc v2.9.9 釋出,IT 團隊的線上 API 文件、技術文件工具API
- ShowDoc v2.8.14 釋出, IT 團隊的線上 API 文件、技術文件工具API
- ShowDoc v2.9.0 釋出, IT 團隊的線上 API 文件、技術文件工具API
- API介面是什麼?產品經理怎麼去看API介面文件?API
- ShowDoc v2.7.0 釋出, IT 團隊的線上 API 文件工具API
- 在Web API程式中使用Swagger做介面文件WebAPISwagger
- 你可能需要知道的API介面文件神器API
- SpringBoot使用Swagger2實現Restful APISpring BootSwaggerRESTAPI
- C#通用文件API介面整合示例-合同識別-智慧文件識別C#API
- Spring Cloud Zuul中使用Swagger彙總API介面文件SpringCloudZuulSwaggerAPI
- 淘寶API介面AG文件接入呼叫方法詳解API
- 將Swagger2文件匯出為HTML或markdown等格式離線閱讀SwaggerHTML
- API文件API
- 節假日查詢 API 介面上線API
- Office文件線上預覽方案
- 宅社AcgClub API上線GCAPI
- Api介面:線上查車輛vin資訊(發動機號)詳情API
- API 線上管理工具 api-momAPI
- Gbase XDM API介面--開啟xdm連線API
- 效率神器——多人線上協作文件