介面文檔產生工具Swagger2的使用

標籤：尾碼名   項目   作用   prope   tab   拋出異常   依賴   聯絡   handlers   

一、什麼是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@EnableSwagger2public 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|圖片和音頻上傳控制器類")@RestControllerpublic 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即可進入文檔頁面

 

介面文檔產生工具Swagger2的使用