您好,登錄后才能下訂單哦!
在進(jìn)行軟件開發(fā)的時(shí)候免不了要寫接口文檔,這些文檔需要明確寫出接口的類型、請(qǐng)求的URL、傳參和返回值格式等信息,用于和前端交互或者提供給測試進(jìn)行接口測試。但是手寫文檔一方面帶給我們很大的工作量,另一方面如果接口有變更則需要頻繁修改并且發(fā)給相關(guān)的人,無形中增加了工作量。小編為大家介紹一個(gè)生成文檔的工具Swagger,上手簡單,學(xué)習(xí)成本低,非常適合開發(fā)SpringBoot項(xiàng)目,現(xiàn)在就跟著小編一起學(xué)習(xí)吧。
首先需要在pom文件中加入swagger2的依賴,依賴的jar包如下圖所示。
<dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.8.0</version> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.8.0</version> </dependency>
編寫Swagger配置類Swagger2Config,在類上增加@Configuration和@EnableSwagger2注解,表明這是一個(gè)配置類,同時(shí)開啟Swagger。如下的信息可以根據(jù)具體情況修改。
@Bean public Docket api() { return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()) .select() // 自行修改為自己的包路徑 .apis(RequestHandlerSelectors.basePackage("com.spring.jpa.user")) .paths(PathSelectors.any()) .build(); } private ApiInfo apiInfo() { return new ApiInfoBuilder() .title("swagger-api文檔") .description("用戶信息相關(guān)") //服務(wù)條款網(wǎng)址 .termsOfServiceUrl("https://baidu.com") .version("1.0") .contact(new Contact("NWSL", "http://baidu.com", "111111@qq.com")) .build(); }
接下來我們需要在Controller層添加注解,@Api(value="/test1", tags="測試用戶接口模塊"), @Api這個(gè)注解是用在請(qǐng)求的類上,表示對(duì)類的說明,其中tags="說明該類的作用,可以在UI界面上看到的注解",value="該參數(shù)沒什么意義,在UI界面上也看到,所以不需要配置"。該注解的使用如下圖所示。
接下來我們需要在方法上添加注解了,如下所示,@ApiOperation、@ApiImplicitParams、@ApiImplicitParam的作用如下圖所示。@ApiResponses:用在請(qǐng)求的方法上,表示一組響@ApiResponse:用在@ApiResponses中,一般用于表達(dá)一個(gè)錯(cuò)誤的響應(yīng)信息。
在方法中的使用如下圖所示。
@ApiOperation(value="添加用戶信息", notes = "添加用戶信息") @ApiImplicitParams({ @ApiImplicitParam(name = "name", value = "用戶姓名", required = true, dataType = "String",paramType = "query"), @ApiImplicitParam(name = "age", value = "用戶年齡", required = true,paramType = "query") })
注意如果是Integer類型,那dataType = "Integer"就可以省略了,寫上了反而在生成的文檔調(diào)用的時(shí)候出錯(cuò)。
接下來我們介紹傳實(shí)體類參數(shù)的注解怎么寫,要使用到@ApiModel、@ApiModelProperty,具體的用法如下圖所示。在接收參數(shù)的實(shí)體類上我們需要添加這兩個(gè)注解,如下圖所示。
接口上注解寫完之后,我們啟動(dòng)服務(wù),然后打開swagger的UI頁面,注意8091端口是我本機(jī)服務(wù)啟動(dòng)的端口,請(qǐng)求的地址如下圖所示。我們可以看到每個(gè)Controller類都生成了文檔,UserController我們?cè)黾恿祟惖淖⑨尅?/p>
接下來我們測試UserController中的接口,如下圖所示,生成了UserController所有的接口文檔,我們首先來看添加用戶接口,如下圖所示,為什么Integer類型的age字段,在生成的接口文檔中參數(shù)類型變成了ref呢?上文提到過的,在寫注解的時(shí)候,dataType = "Integer"要省略掉,不然會(huì)出現(xiàn)這個(gè)問題。正確的如下所示,可以看到age為Integer類型了。
我們可以看到在接口的右側(cè)有Try it out,點(diǎn)擊該按鈕進(jìn)入到調(diào)用頁面。在如下的頁面填寫完參數(shù)之后執(zhí)行Execute即可,還是age參數(shù)ref的問題,此時(shí)執(zhí)行會(huì)提示錯(cuò)誤,要把注釋中的Integer類型去掉,在執(zhí)行即可。
接下來我們看一個(gè)Get請(qǐng)求,這個(gè)請(qǐng)求不需要傳參,直接執(zhí)行即可,結(jié)果如下圖所示。我們可以看到Swagger生成的restful形式的接口文檔,非常方便調(diào)試。
接下來我們執(zhí)行update的接口,這是上面我們用實(shí)體類接收參數(shù)的方法,可以看到參數(shù)的例子,我們修改完參數(shù)值后執(zhí)行即可。以上swagger2與springboot就集成完了。
免責(zé)聲明:本站發(fā)布的內(nèi)容(圖片、視頻和文字)以原創(chuàng)、轉(zhuǎn)載和分享為主,文章觀點(diǎn)不代表本網(wǎng)站立場,如果涉及侵權(quán)請(qǐng)聯(lián)系站長郵箱:is@yisu.com進(jìn)行舉報(bào),并提供相關(guān)證據(jù),一經(jīng)查實(shí),將立刻刪除涉嫌侵權(quán)內(nèi)容。