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

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

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

我們先來看看具體效果:

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

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

構(gòu)建RESTful API

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

添加Swagger2依賴

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

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

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

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

/**
 * 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();
    }

}

編輯文檔接口信息

先看一個(gè)例子:

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

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

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

value: 表示接口名稱

notes: 表示接口詳細(xì)描述

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

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

paramType：參數(shù)位置

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

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

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

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

name：參數(shù)名

dataType：參數(shù)類型

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

value：參數(shù)的描述

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

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

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

code：狀態(tài)碼

message：返回自定義信息

response：拋出異常的類

訪問文檔

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

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

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