摘要：使用生成，我們可以得到交互式文檔，自動生成代碼的以及的發現特性等。方法指定掃描的包會生成文檔默認是顯示所有接口可以用注解標識該接口不顯示。

程序員都很希望別人能寫技術文檔，自己卻很不愿意寫文檔。因為接口數量繁多,并且充滿業務細節,寫文檔需要花大量的時間去處理格式排版,代碼修改后還需要同步修改文檔,經常因為項目時間緊等原因導致文檔滯后于代碼，接口調用方的抱怨聲不絕于耳。而程序員是最擅長"偷懶"的職業了,自然會有多種多樣的自動生成文檔的插件.今天要介紹的就是Swagger.

Swagger是一個簡單但功能強大的API表達工具。它具有地球上最大的API工具生態系統，數以千計的開發人員，使用幾乎所有的現代編程語言，都在支持和使用Swagger。使用Swagger生成API，我們可以得到交互式文檔，自動生成代碼的SDK以及API的發現特性等。

我們先來看看具體效果:

可以看到Swagger-Ui是以controller分類,點擊一個controller可以看到其中的具體接口,再點擊接口就可以看到接口的信息了,如圖:

我們可以看到該接口的請求方式,返回數據信息和需要傳遞的參數.而且以上數據是自動生成的,即使代碼有一些修改,Swagger文檔也會自動同步修改.非常的方便.

構建RESTful API

在使用Swagger2前我們需要有一個RESTful API的項目. Spring-Boot創建RESTful API項目非常的方便和快速,這里不再介紹如何創建,需要的可以參照項目代碼

添加Swagger2依賴

在pom.xml文件中加入以下依賴.

        
            io.springfox
        springfox-swagger2
        2.7.0
        
        
            io.springfox
            springfox-swagger-ui
            2.7.0
        

創建Swagger2的Java配置類

通過@Configuration注解，表明它是一個配置類，@EnableSwagger2 注解開啟swagger2。apiInfo() 方法配置一些基本的信息。createRestApi() 方法指定掃描的包會生成文檔,默認是顯示所有接口,可以用@ApiIgnore注解標識該接口不顯示。

/**
 * Created by Yuicon on 2017/5/20.
 * https://github.com/Yuicon
 */
@Configuration
@EnableSwagger2
public class Swagger2 {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                // 指定controller存放的目錄路徑
                .apis(RequestHandlerSelectors.basePackage("com.digag.web"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                 // 文檔標題
                .title("DigAg")
                // 文檔描述
                .description("https://github.com/Yuicon")
                .termsOfServiceUrl("https://github.com/Yuicon")
                .version("v1")
                .build();
    }

}

編輯文檔接口信息

先看一個例子:

    @ApiOperation(value="創建條目")
    @RequestMapping(method = RequestMethod.POST)
    public JsonResult saveEntry(@RequestBody @ApiParam(value = "條目對象", required = true) Entry entry, HttpServletRequest request) {
        return entryService.create(entry, request);
    }

Swagger2提供了一些注解來豐富接口的信息,常用的有:

@ApiOperation：用在方法上，說明方法的作用

value: 表示接口名稱

notes: 表示接口詳細描述

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

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

paramType：參數位置

header 對應注解：@RequestHeader

query 對應注解：@RequestParam

path 對應注解: @PathVariable

body 對應注解: @RequestBody

name：參數名

dataType：參數類型

required：參數是否必須傳

value：參數的描述

defaultValue：參數的默認值

@ApiResponses：用于表示一組響應

@ApiResponse：用在@ApiResponses中，一般用于表達一個錯誤的響應信息

code：狀態碼

message：返回自定義信息

response：拋出異常的類

訪問文檔

swagger2文檔的默認地址是 /swagger-ui.html, 本地開發的訪問 http://localhost:8080/swagger-ui.html就可以看到自動生成的文檔了.

完整結果示例可查看項目代碼

Swagger注解文檔
Swagger官方網站