在進行軟件開發(fā)的時候免不了要寫接口文檔，這些文檔需要明確寫出接口的類型、請求的URL、傳參和返回值格式等信息，用于和前端交互或者提供給測試進行接口測試。但是手寫文檔一方面帶給我們很大的工作量，另一方面如果接口有變更則需要頻繁修改并且發(fā)給相關(guān)的人，無形中增加了工作量。小編為大家介紹一個生成文檔的工具Swagger，上手簡單，學(xué)習(xí)成本低，非常適合開發(fā)SpringBoot項目，現(xiàn)在就跟著小編一起學(xué)習(xí)吧。
吳起網(wǎng)站制作公司哪家好，找創(chuàng)新互聯(lián)！從網(wǎng)頁設(shè)計、網(wǎng)站建設(shè)、微信開發(fā)、APP開發(fā)、自適應(yīng)網(wǎng)站建設(shè)等網(wǎng)站項目制作，到程序開發(fā)，運營維護。創(chuàng)新互聯(lián)從2013年創(chuàng)立到現(xiàn)在10年的時間，我們擁有了豐富的建站經(jīng)驗和運維經(jīng)驗，來保證我們的工作的順利進行。專注于網(wǎng)站建設(shè)就選創(chuàng)新互聯(lián)。
首先需要在pom文件中加入swagger2的依賴，依賴的jar包如下圖所示。
io.springfox springfox-swagger2 2.8.0 io.springfox springfox-swagger-ui 2.8.0
編寫Swagger配置類Swagger2Config，在類上增加@Configuration和@EnableSwagger2注解，表明這是一個配置類，同時開啟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這個注解是用在請求的類上，表示對類的說明，其中tags="說明該類的作用，可以在UI界面上看到的注解"，value="該參數(shù)沒什么意義，在UI界面上也看到，所以不需要配置"。該注解的使用如下圖所示。
接下來我們需要在方法上添加注解了，如下所示，@ApiOperation、@ApiImplicitParams、@ApiImplicitParam的作用如下圖所示。@ApiResponses：用在請求的方法上，表示一組響@ApiResponse：用在@ApiResponses中，一般用于表達一個錯誤的響應(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ù)的注解怎么寫，要使用到@ApiModel、@ApiModelProperty，具體的用法如下圖所示。在接收參數(shù)的實體類上我們需要添加這兩個注解，如下圖所示。
接口上注解寫完之后，我們啟動服務(wù)，然后打開swagger的UI頁面，注意8091端口是我本機服務(wù)啟動的端口，請求的地址如下圖所示。我們可以看到每個Controller類都生成了文檔，UserController我們增加了類的注釋。
接下來我們測試UserController中的接口，如下圖所示，生成了UserController所有的接口文檔，我們首先來看添加用戶接口，如下圖所示，為什么Integer類型的age字段，在生成的接口文檔中參數(shù)類型變成了ref呢？上文提到過的，在寫注解的時候，dataType = "Integer"要省略掉，不然會出現(xiàn)這個問題。正確的如下所示，可以看到age為Integer類型了。
我們可以看到在接口的右側(cè)有Try it out，點擊該按鈕進入到調(diào)用頁面。在如下的頁面填寫完參數(shù)之后執(zhí)行Execute即可，還是age參數(shù)ref的問題，此時執(zhí)行會提示錯誤，要把注釋中的Integer類型去掉，在執(zhí)行即可。
接下來我們看一個Get請求，這個請求不需要傳參，直接執(zhí)行即可，結(jié)果如下圖所示。我們可以看到Swagger生成的restful形式的接口文檔，非常方便調(diào)試。
接下來我們執(zhí)行update的接口，這是上面我們用實體類接收參數(shù)的方法，可以看到參數(shù)的例子，我們修改完參數(shù)值后執(zhí)行即可。以上swagger2與springboot就集成完了。
