在開發過程中,有時候我們需要不停的測試接口,自測,或者交由測試測試接口,我們需要構建一個文檔,都是單獨寫,太麻煩了,現在使用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才能獲取到對應的參數...