使用RESTful服務通常是涉及到多個終端的團隊，比如Android、iOS、WEB等。為了讓大家溝通順暢，通常我們需要編寫一份詳細的RESTful業務接口文檔

使用Swagger2有助于我們編寫一份詳細的RESTful業務接口文檔，過去經常會使用Word或者Excel，但是接口非常多，細節又復雜，如果由程序員高質量的輸出一個文檔，經常耗時長而且效果也不好。Swagger2能將代碼和注釋說明很好結合在一塊。既減輕了研發人員的負擔，又能輸出高質量的文檔。
下面說下如何去使用

pom.xml中添加Swagger2依賴

2.6.1版本是16年11月才更新的版本

<!--引入Swagger2的依賴-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.6.1</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.6.1</version>
        </dependency>

創建Swagger2配置類

@Configuration注解，讓Spring來加載該類配置。
@EnableSwagger2注解來啟用Swagger2。
apiInfo()用來創建該Api的基本信息（這些基本信息會展現在文檔頁面中）。
RequestHandlerSelectors.basePackage()中填的是你controller的目錄
apiInfo()方法中termsOfServiceUrl和contact可以用Contact的對象代替
Swagger2已經不支持String類型的contact

Paste_Image.png

Contact對象中name表示作者，url通常作為項目的鏈接，代替之前的termsOfServiceUrl方法，email的話不用我多說了吧，不想寫的話可以為空字符串

Paste_Image.png

createRestApi函數創建Docket的Bean之后，apiInfo()用來創建該Api的基本信息（這些基本信息會展現在文檔頁面中）。select()函數返回一個ApiSelectorBuilder實例用來控制哪些接口暴露給Swagger來展現，采用指定掃描的包路徑來定義，Swagger會掃描該包下所有Controller定義的API，并產生文檔內容（除了被@ApiIgnore指定的請求）。

@Configuration
@EnableSwagger2
public class Swagger2 {
        @Bean
        public Docket createRestApi() {
            return new Docket(DocumentationType.SWAGGER_2)
                    .apiInfo(apiInfo())
                    .select()
                    .apis(RequestHandlerSelectors.basePackage("com.pjb.controller"))
                    .paths(PathSelectors.any())
                    .build();
        }
    private ApiInfo apiInfo() {
        Contact contact=new Contact("作者名",
          "http://www.lxweimin.com/u/f192766abeab","email地址");
        return new ApiInfoBuilder()
                .title("Spring Boot中使用Swagger2")
                .description("Hello Swagger2")
                //.termsOfServiceUrl("http://www.lxweimin.com/u/f192766abeab")
                //.contact("作者名")
                .contact(contact)
                .version("1.0")
                .build();
    }
}

然后通過創建實體類和controller來簡單測試下
具體的可以參照

簡書作者 程序猿DD的文章Spring Boot中使用Swagger2構建強大的RESTful API文檔

http://www.lxweimin.com/p/8033ef83a8ed

注意

記得在UserController中需要id輸入的方法的注解少了個參數配置： paramType="path"，不然所有的參數類型都會是body，獲取不到請求參數。例如
@ApiImplicitParam(name = "id", value = "用戶ID", required = true, dataType = "Long"，paramType = "path")；

訪問：http://localhost:8080/swagger-ui.html
就能看到前文所展示的RESTful API的頁面。

Paste_Image.png

選中所寫的UserController后出現5個方法讓你測試

Paste_Image.png

具體的測試效果可以自己來測試玩玩