關於 Swagger

Swagger能成為最受歡迎的REST APIs文檔生成工具之一，有以下幾個原因：

• Swagger 可以生成一個具有互動性的API控制臺，開發者可以用來快速學習和嘗試API。
• Swagger 可以生成客戶端SDK代碼用於各種不同的平臺上的實現。
• Swagger 文件可以在許多不同的平臺上從代碼註釋中自動生成。
• Swagger 有一個強大的社區，裏面有許多強悍的貢獻者。

Swagger 文檔提供了一個方法，使我們可以用指定的 JSON 或者 YAML 摘要來描述你的 API，包括了比如 names、order 等 API 信息。

你可以通過一個文本編輯器來編輯 Swagger 文件，或者你也可以從你的代碼註釋中自動生成。各種工具都可以使用 Swagger 文件來生成互動的 API 文檔。

下面我們開始在Spring Boot中使用Swagger2構建RESTful APIs

第一步，在pom.xml中加入Swagger2的依賴

<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配置類（註意配置類須與application同級目錄）

/**
 * Swagger2配置類
 * 在於Springboot集成時，需與application同目錄
 * 通過註解@Configuration，讓Spring來加載該配置
 * 通過註解@EnableSwagger2，來啟動swagger2
 */
@Configuration
@EnableSwagger2
 
public class Swagger2 {
    /**
     * 創建API應用
     *
     * @return
     */
    @Bean
    public Docket createRestApi() {
        Docket docket = new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.web"))//註：該路徑指定為需要加載Swagger的路徑，只有路徑中的API才會被Swagger管理
                .paths(PathSelectors.any()).build();
        return docket;
    }


    /**
     * 創建改API的基本信息（這些基本信息會展示在文檔頁面中）
     * 訪問地址： http://項目實際地址/swagger-ui.html
     * @return
     */
    public ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Spring Boot中使用Swagger2構建RESTful APIs")
                .description("了解更多請聯系：Misme")
                .termsOfServiceUrl("http://www.cnblogs.com/MisMe/")
                .contact("Misme")
                .version("1.0")
                .build();
    }
}

第三步，添加文檔內容，在需要的地方添加註解

@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 "具體方法";
    }
}

註解詳解：

• @Api：修飾整個類，描述Controller的作用
• @ApiOperation：描述一個類的一個方法，或者說一個接口
• @ApiParam：單個參數描述
• @ApiModel：用對象來接收參數
• @ApiProperty：用對象接收參數時，描述對象的一個字段
• @ApiResponse：HTTP響應其中1個描述
• @ApiResponses：HTTP響應整體描述
• @ApiIgnore：使用該註解忽略這個API
• @ApiError ：發生錯誤返回的信息
• @ApiImplicitParam：一個請求參數
• @ApiImplicitParams：多個請求參數

Spring Boot中使用Swagger2構建RESTful APIs