接口文檔生成工具Swagger2的使用

1、什麼是Swagger

　　Swagger 是一個規範和完整的框架，用於生成、描述、調用和可視化 RESTful 風格的 Web 服務。整體目標是使客戶端和文件系統做爲服務器以一樣的速度來更新。文件的方法，參數和模型緊密集成到服務器端的代碼，容許API來始終保持同步。

　　做用：

　　1. 接口的文檔在線自動生成。

　　2. 功能測試。

2、在Maven中添加依賴

　　

<dependency>

    <groupId>io.springfox</groupId>

    <artifactId>springfox-swagger2</artifactId>

    <version>2.2.2</version>

</dependency>

<dependency>

    <groupId>io.springfox</groupId>

    <artifactId>springfox-swagger-ui</artifactId>

    <version>2.2.2</version>

</dependency>

3、建立Swagger2的配置類

　　

/** * Swagger2 配置類 * 在與spring boot 集成時，放在與application.java 同級的目錄下 * 經過@Configuration註解，讓spring來加載該配置 * 再經過@EnableSwagger2註解來啓動Swagger2 */ @Configuration @EnableSwagger2 public class Swagger2 { /** * 建立API應用 * appinfo()增長API相關信息 * 經過select()函數返回一個ApiSelectorBuilder實例，用來控制那些接口暴露給Swagger來展示 * 本例採用置頂掃描的包路徑來定義指定要創建API的目錄 * * @return
     */ @Bean public Docket createRestApi() { Docket docket = new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()) .select() .apis(RequestHandlerSelectors.basePackage("com.shuke.chat")) .paths(PathSelectors.any()).build(); return docket; } /** * 建立改API的基本信息（這些基本信息會展現在文檔頁面中） * 訪問地址： http://項目實際地址/swagger-ui.html * @return
     */
    public ApiInfo apiInfo() { return new ApiInfoBuilder() .title("使用websocket實現實時通信 APIs") .description("瞭解更多請聯繫：shuke") .termsOfServiceUrl("http://www.baidu.com") .contact("shuke") .version("1.0") .build(); } }

4、Swagger2 的註解使用

　　

@Api：用在類上，說明該類的做用。

@ApiOperation：註解來給API增長方法說明。

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

@ApiImplicitParam：用來註解來給方法入參增長說明。

@ApiResponses：用於表示一組響應

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

    *  code：數字，例如400

    *  message：信息，例如"請求參數沒填好"

    *  response：拋出異常的類   

@ApiModel：描述一個Model的信息（通常用在請求參數沒法使用@ApiImplicitParam註解進行描述的時候）

    *  @ApiModelProperty：描述一個model的屬性

 

注意：@ApiImplicitParam的參數說明：

paramType：指定參數放在哪一個地方	header：請求參數放置於Request Header，使用@RequestHeader獲取 query：請求參數放置於請求地址，使用@RequestParam獲取 path：（用於restful接口）-->請求參數的獲取：@PathVariable body：（不經常使用） form（不經常使用）
name：參數名
dataType：參數類型
required：參數是否必須傳	true | false
value：說明參數的意思
defaultValue：參數的默認值

 

/** * @author shuke * @date 2018/10/16 */ @Api("ChatInfoController|圖片和音頻上傳控制器類") @RestController public class ChatInfoController { /** * 上傳圖片接口 * @param attach 文件對象 * @param request http請求 * @return imgSrc：上傳後圖片文件的路徑 */ @ApiOperation(value = "上傳圖片",notes = "文件不能超過20M大小，後綴名爲png，jpg，gif") @RequestMapping(value = "/uploadImg",method = RequestMethod.POST) @ResponseBody public String uploadImg(@RequestParam("file") MultipartFile attach,HttpServletRequest request) { System.out.println("上傳圖片"); return FileUp.upFile(attach, request, Constants.IMAGE, true); } /** * 上傳語音接口 * @param attach 文件對象 * @param request http請求 * @return audioSrc:上傳後語音文件的路徑 */ @ApiOperation(value = "上傳語音",notes = "文件不能超過20M大小，後綴名爲MP3，silk，flv") @RequestMapping(value = "/uploadAudio",method = RequestMethod.POST) @ResponseBody public String uploadAudio( @RequestParam("file") MultipartFile attach,HttpServletRequest request) { System.out.println("上傳語音"); return FileUp.upFile(attach, request, Constants.AUDIO, true); } }

添加註解後啓動springboot，輸入http://localhost:8080/swagger-ui.html便可進入文檔頁面