學(xué)習(xí)背景
或許我們習(xí)慣用postman調(diào)試接口杉允,但是你會(huì)發(fā)現(xiàn)赘娄,每次調(diào)試一個(gè)接口時(shí)都需要把路徑和參數(shù)寫上去,有的時(shí)候還容易寫錯(cuò)故响,大大耽誤了咱們的開發(fā)時(shí)間。
swagger是什么東西颁独?
swagger用于定義API文檔彩届。
優(yōu)點(diǎn)
- 前后端分離開發(fā)
- API文檔非常明確
- 測(cè)試的時(shí)候不需要再使用URL輸入瀏覽器的方式來訪問Controller
傳統(tǒng)的輸入U(xiǎn)RL的測(cè)試方式對(duì)于post請(qǐng)求的傳參比較麻煩(當(dāng)然,可以使用postman這樣的瀏覽器插件) - spring-boot與swagger的集成簡(jiǎn)單的一b
實(shí)踐
- 項(xiàng)目前準(zhǔn)備一個(gè)maven+spring boot項(xiàng)目(自己去ij IDE上自動(dòng)生成一個(gè))
第一步:
在maven 中加入下面?zhèn)z個(gè)依賴誓酒,一定是2.6.1之后的樟蠕,之前的我試過幾個(gè)不能用:
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.6.1</version>
<scope>compile</scope>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.6.1</version>
<scope>compile</scope>
</dependency>
第二步:
寫一個(gè)配置類:
@EnableSwagger2
@Configuration
class Swagger2 {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select() //RequestHandlerSelectors.any(),所有的路勁都去掃描
//這個(gè)掃描包的意思一樣靠柑,固定路勁就去相應(yīng)的路勁掃描
.apis(RequestHandlerSelectors.basePackage("com.example.demo.talkCloud.controller"))
.paths(PathSelectors.any())
.build();
}
//就是對(duì)生成的api文檔的一個(gè)描述
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("文檔標(biāo)題")
.description("文檔描述")
.termsOfServiceUrl("相關(guān)url")
.contact("名字-UP主")
.version("版本:1.0")
.build();
}
}
【注意】:實(shí)現(xiàn)這兩步就能完成文檔的生成了寨辩,可以嘗試用localhost:8080/swagger-ui.html 訪問,端口是spring boot 啟動(dòng)時(shí)設(shè)置的歼冰,自己看靡狞。
第三步:
去你的controller層用注解標(biāo)記Controller,常用的注解我寫在下面了停巷,這些注解都是為了豐富api文檔誕生的耍攘。這里先舉個(gè)例如:
@ApiImplicitParams({
@ApiImplicitParam(name = "Authorization", value = "Authorization token",
required = true, dataType = "string", paramType = "header"),
@ApiImplicitParam(name = "studentId", value = "學(xué)生id", dataType = "Long", paramType = "query"),
@ApiImplicitParam(name = "subjectId", value = "科目id", dataType = "Integer", paramType = "query"),
@ApiImplicitParam(name = "pageSize", value = "頁(yè)大小", dataType = "Integer", paramType = "query"),
@ApiImplicitParam(name = "pageNo", value = "第幾頁(yè)", dataType = "Integer", paramType = "query"),
})
@ApiOperation(value = "學(xué)生課程表獲取", httpMethod = "GET", response = ResponseEntity.class)
@RequestMapping(value = "student/course/table", method = RequestMethod.GET)
public ResponseEntity saveResourceSec(
@RequestParam(name = "studentId") Long studentId,
@RequestParam(name = "subjectId", required = false) Integer subjectId,
@RequestParam(value = "pageSize", defaultValue = "25") Integer pageSize,
@RequestParam(value = "pageNo", defaultValue = "1") Integer pageNo,
@RequestParam(value = "modifiedOn", required = false) Date modifiedOn
) {
PageWrapper<CourseScheduleObject> result = studentCourseTableService.getStudentCourseById(studentId, subjectId, pageNo, pageSize, modifiedOn);
return ResponseEntity.ok(result);
}
【常見注解解讀】
其實(shí)自己領(lǐng)悟一下就好榕栏,就按照單詞表名意思畔勤,簡(jiǎn)單!
- @Api:用在類上扒磁,說明該類的作用
- @ApiOperation:用在方法上庆揪,說明方法的作用
- @ApiImplicitParams:用在方法上包含一組參數(shù)說明
- @ApiImplicitParam:用在@ApiImplicitParams注解中,指定一個(gè)請(qǐng)求參數(shù)的各個(gè)方面
- paramType:
- header-->請(qǐng)求參數(shù)的獲确镣小:@RequestHeader
- query-->請(qǐng)求參數(shù)的獲雀组弧:@RequestParam
- path(用于restful接口)-->請(qǐng)求參數(shù)的獲取@PathVariable
- cookie:which are passed in the Cookie header, such as Cookie: debug=0; csrftoken=BUSe35dohU3O1MZvDCU
- body(不常用)
- form(不常用)
- name:參數(shù)名
- value:對(duì)參數(shù)的描述
- dataType:參數(shù)類型
- required:參數(shù)是否必須傳
- defaultValue:參數(shù)的默認(rèn)值
- paramType:
- @ApiResponses:用于表示一組響應(yīng)
- @ApiResponse:用在@ApiResponses中,一般用于表達(dá)一個(gè)錯(cuò)誤的響應(yīng)信息
- code:數(shù)字兰伤,例如400
- message:信息内颗,例如"請(qǐng)求參數(shù)沒填好"
- response:拋出異常的類