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

一、什么是Swagger

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

　　作用：

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

　　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>

三、創建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();
    }
}

四、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即可進入文檔頁面