在開發過程中,有時候我們需要不停的測試接口,自測,或者交由測試測試接口,我們需要構建一個文檔,都是單獨寫,太麻煩了,現在使用springboot集成swagger2來構建RESTful API文檔,可以在訪問接口上,直接添加注釋

?

先介紹一下開發環境:

jdk版本是1.8

springboot的版本是1.4.1

開發工具為 intellij idea

?

我們先引入swagger2的jar包,pom文件引入依賴如下:

<dependency><groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.6.1</version> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.6.1</version> </dependency>

?

接下來,我們構建swagger2的配置類,代碼如下:

?

//注解開啟 swagger2 功能 @EnableSwagger2 //注解標示,這是一個配置類,@Configuation注解包含了@Component注解 //可以不用在使用@Component注解標記這是個bean了, @Configuration public class Swagger2 { /** * 通過 createRestApi函數來構建一個DocketBean * 函數名,可以隨意命名,喜歡什么命名就什么命名 */ @Bean public Docket createRestApi() { return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo())//調用apiInfo方法,創建一個ApiInfo實例,里面是展示在文檔頁面信息內容 .select() //控制暴露出去的路徑下的實例 //如果某個接口不想暴露,可以使用以下注解 //@ApiIgnore 這樣,該接口就不會暴露在 swagger2 的頁面下 .apis(RequestHandlerSelectors.basePackage("com.example")) .paths(PathSelectors.any()) .build(); } //構建 api文檔的詳細信息函數 private ApiInfo apiInfo() { return new ApiInfoBuilder() //頁面標題 .title("Spring Boot 測試使用 Swagger2 構建RESTful API") //創建人 .contact("賀小五") //版本號 .version("1.0") //描述 .description("API 描述") .build(); } }

?

swagger2的配置類已經配置好了,下面,我們就在主函數里面隨意寫一些接口吧

?

@SpringBootApplication(scanBasePackages = {"com"}) //該注解包含了@Controller和@ResponseBody兩個注解 @RestController public class DemoApplication{ public static void main(String[] args) { SpringApplication.run(DemoApplication.class, args); } /** * 以下函數的注釋,不增加注解了,將在下面統一做描述 */ @ApiOperation(value = "測試post請求",notes="注意事項") @ApiImplicitParam(dataType = "User",name = "user",value = "用戶信息",required = true) @RequestMapping(value = "/testPost",method = RequestMethod.POST) public String testPost(@RequestBody User user){ return "success"; } @ApiOperation(value = "測試get請求",notes="注意事項") @ApiImplicitParam(name = "id",value = "用戶id",dataType = "String",paramType = "path") @RequestMapping(value = "/testGet/{id}",method = RequestMethod.GET) public String testGet(@PathVariable String id){ return id; } @ApiOperation(value = "測試組合注解",notes="注意事項") @ApiImplicitParams({ @ApiImplicitParam(dataType = "User",name = "user",value = "用戶信息",required = true,paramType = "body"), @ApiImplicitParam(dataType = "string",name = "id",value = "用戶id",required = true,paramType = "path") }) @RequestMapping(value = "/joinAnnotation/{id}",method = RequestMethod.POST) public User joinAnnotation(@PathVariable String id,@RequestBody User user){ return user; } @ApiIgnore public String testIgnore(){ return "success"; } }

?

你們別吐槽我的方法命名........將就著看吧...測試demo,命名隨意了些(其實是我英語不太好....哈哈哈哈哈.....)

?

寫好controller后,我們可以訪問以下地址:http://localhost:8080/swagger-ui.html,如果你沒引入swagger2依賴,你是訪問不了的..然后你會得到一個如下頁面

?

上面的頁面,就是swagger2里面的頁面,可以發現, apiInfo里面設置的內容在左邊展示出來了,demo-application其實就是controller的類名,右邊有三個按鈕,分別是 Show/Hide,List Opertions和Expand Operations,三個按鈕都可以打開,類下的接口,點擊后,會得到如下一個效果頁面:

可以發現,展示出來了,controller下的三個接口(其實有四個,只不過有一個我們用注解忽略了,在這不展示而已..)

?

上面三個接口,在我們注解里面添加的,都有展示,請求方式,接口名稱,現在我們打開某個接口,看看具體內容,接口內的內容,我不在用文字描述,我直接在截圖里面添加描述了.見諒....

?

這個,,截圖比較爛,各位將就著看吧..別嫌棄...,我們點擊try it out 按鈕,就會發送請求,結果如下:

?

以上就是比較簡單的demo測試文檔啦,如果各位想配置更詳細,就去官網看吧..地址我貼出來:

swagger官網地址:http://swagger.io/

?

下面就是介紹,上面接口中,上面關于swagger2本人常用注解的一些描述

?

?

本人常用注解說明：

@ApiOperation：用在方法上，說明方法的作用

? ? value: 表示接口名稱

? ? notes: 表示接口詳細描述?

@ApiImplicitParams：用在方法上包含一組參數說明

@ApiImplicitParam：用在@ApiImplicitParams注解中，指定一個請求參數的各個方面

paramType：參數位置

• header 對應注解：@RequestHeader
• query 對應注解：@RequestParam
• path ?對應注解: @PathVariable
• body?對應注解: @RequestBody

name：參數名

dataType：參數類型

required：參數是否必須傳

value：參數的描述

defaultValue：參數的默認值

@ApiResponses：用于表示一組響應

@ApiResponse：用在@ApiResponses中，一般用于表達一個錯誤的響應信息

code：狀態碼

message：返回自定義信息

response：拋出異常的類

@ApiIgnore: 表示該接口函數不對swagger2開放展示

以上這些就是我測試過的注解,并沒有深究,有興趣的,可以看看其它注解,或者源碼,會比我描述的全很多,

?

對了,需要注意下,@ApiImplicitParam注解下的paramType屬性,會影響接口的測試,如果設置的屬性跟spring的注解對應不上,會獲取不到參數,例如:paramType=path,函數內卻使用@RequestParam注解,這樣,可能會獲取不到傳遞進來的參數,需要按照上面進行對應,將@RequestParam注解改為@PathVariable才能獲取到對應的參數...

總結

以上是生活随笔為你收集整理的springboot集成swagger2构建RESTful API文档的全部內容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網站內容還不錯，歡迎將生活随笔推薦給好友。