學(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：拋出異常的類
