springboot集成swagger2構建RESTful API文檔

在開發過程當中,有時候咱們須要不停的測試接口,自測,或者交由測試測試接口,咱們須要構建一個文檔,都是單獨寫,太麻煩了,如今使用springboot集成swagger2來構建RESTful API文檔,能夠在訪問接口上,直接添加註釋

 

先介紹一下開發環境:

1. jdk版本是1.8
2. springboot的版本是1.4.1
3. 開發工具爲 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：用在方法上，說明方法的做用

1.     value: 表示接口名稱
2.     notes: 表示接口詳細描述 

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

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

1. paramType：參數位置

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

1. name：參數名
2. dataType：參數類型
3. required：參數是否必須傳
4. value：參數的描述
5. defaultValue：參數的默認值

@ApiResponses：用於表示一組響應

@ApiResponse：用在@ApiResponses中，通常用於表達一個錯誤的響應信息

1. code：狀態碼
2. message：返回自定義信息
3. response：拋出異常的類

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

以上這些就是我測試過的註解,並無深究,有興趣的,能夠看看其它註解,或者源碼,會比我描述的全不少,

 

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