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

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

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

我們先來看看具體效果:

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

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

構(gòu)建RESTful API

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

添加Swagger2依賴

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

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

創(chuàng)建Swagger2的Java配置類

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

/**
 * 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()
                 // 文檔標(biāo)題
                .title("DigAg")
                // 文檔描述
                .description("https://github.com/Yuicon")
                .termsOfServiceUrl("https://github.com/Yuicon")
                .version("v1")
                .build();
    }

}

編輯文檔接口信息

先看一個例子:

    @ApiOperation(value="創(chuàng)建條目")
    @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: 表示接口詳細(xì)描述

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

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

paramType：參數(shù)位置

header 對應(yīng)注解：@RequestHeader

query 對應(yīng)注解：@RequestParam

path 對應(yīng)注解: @PathVariable

body 對應(yīng)注解: @RequestBody

name：參數(shù)名

dataType：參數(shù)類型

required：參數(shù)是否必須傳

value：參數(shù)的描述

defaultValue：參數(shù)的默認(rèn)值

@ApiResponses：用于表示一組響應(yīng)

@ApiResponse：用在@ApiResponses中，一般用于表達(dá)一個錯誤的響應(yīng)信息

code：狀態(tài)碼

message：返回自定義信息

response：拋出異常的類

訪問文檔

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

完整結(jié)果示例可查看項目代碼

Swagger注解文檔
Swagger官方網(wǎng)站