寫(xiě)在前面

使用RESTful API作為Web服務(wù)對(duì)外提供服務(wù)的入口，基本上已經(jīng)成為了標(biāo)準(zhǔn)，在提供REST API的同時(shí)，如何進(jìn)行
API文檔管理是一個(gè)較為麻煩的事情，作為開(kāi)發(fā)人員我們都了解API文檔的重要性，但總是嫌其編寫(xiě)的麻煩，Swagger的
出現(xiàn)很好地幫我們解決文檔編寫(xiě)的事情，開(kāi)發(fā)人員可以采取自己喜歡的姿勢(shì)進(jìn)行API文檔編寫(xiě)，例如使用Swagger-Editor
進(jìn)行API的提前設(shè)計(jì)，進(jìn)而使用Swagger-Codegen來(lái)生成多種語(yǔ)言的客戶端代碼，使用Swagger-UI來(lái)進(jìn)行API文檔
的直觀查看，當(dāng)然你也可以在代碼中直接進(jìn)行API文檔的編寫(xiě)，本教程將介紹如何在Spring REST API項(xiàng)目中，進(jìn)行
Swagger2的集成，這樣便可以很方便地進(jìn)行API文檔編寫(xiě)了。

在本篇教程中將使用Springfox的Swagger實(shí)現(xiàn)來(lái)集成，關(guān)于 Swagger2 和 Springfox 的介紹如下：

• Swagger 2
• Springfox

項(xiàng)目配置

本教程將假設(shè)你已經(jīng)有了一個(gè)Spring REST服務(wù)，如果沒(méi)有話，可以參考Spring官方項(xiàng)目示例：

Building a RESTful Web Service

添加Maven依賴

在你的Spring REST項(xiàng)目中添加maven依賴，打開(kāi)項(xiàng)目的pom.xml，添加如下內(nèi)容：

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.6.1</version>
</dependency>

在項(xiàng)目中集成Swagger2

集成Swagger2

首先創(chuàng)建一個(gè)SwaggerConfiguration類，如下：

@Configuration
@EnableSwagger2
public class SwaggerConfiguration {                                    
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)  
          .select()                                  
          .apis(RequestHandlerSelectors.any())              
          .paths(PathSelectors.any())                          
          .build();                                           
    }
}

通過(guò)使用@EnableSwagger2注解來(lái)開(kāi)啟Swagger2，在整個(gè)類中最重要的便是Docket的Bean，Docket定義了
Swagger的版本、需要暴露的API等信息，我們來(lái)看看Docket生成后都做了些什么工作：

1. 創(chuàng)建一個(gè)Docket對(duì)象
2. 調(diào)用select()方法，生成ApiSelectorBuilder對(duì)象實(shí)例，該對(duì)象負(fù)責(zé)定義外漏的API入口
3. 通過(guò)使用RequestHandlerSelectors和PathSelectors來(lái)提供Predicate，在此我們使用any()方法，將所有API都通過(guò)Swagger進(jìn)行文檔管理

如果你的項(xiàng)目是一個(gè)Spring Boot項(xiàng)目，上面的配置已經(jīng)OK了，可以開(kāi)始進(jìn)行API文檔的編寫(xiě)了，但如果你的項(xiàng)目
不是Spring Boot項(xiàng)目，只是Spring項(xiàng)目的話，需要稍微多做些工作。

非Spring Boot項(xiàng)目中，配置Resource Handler

由于沒(méi)有使用Spring Boot，這樣就不能自動(dòng)配置Resource Handler，需要自己進(jìn)行下配置，因?yàn)槲覀兘酉聛?lái)要使用
Swagger UI，它有些靜態(tài)資源需要加載，新建一個(gè)類，繼承WebMvcConfigurerAdapter并使用@EnableWebMvc注解，然后添加如下代碼，如果你已經(jīng)有了一個(gè)這樣的類，可以進(jìn)行將以下代碼添加至該類：

@Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {
    registry.addResourceHandler("swagger-ui.html")
      .addResourceLocations("classpath:/META-INF/resources/");

    registry.addResourceHandler("/webjars/**")
      .addResourceLocations("classpath:/META-INF/resources/webjars/");
}

體驗(yàn)成果

假設(shè)我是使用Spring REST官方示例項(xiàng)目的話，打開(kāi)瀏覽器，輸入：

http://localhost:8080/v2/api-docs

你應(yīng)該會(huì)看到JSON格式的API文檔，如下圖所示：

Swagger2 API Docs

這樣的JSON文件，讀起來(lái)是很不方便的，接下來(lái)我們用Swagger UI來(lái)進(jìn)行查看。

Swagger UI

Swagger UI提供了Web頁(yè)面以方便開(kāi)發(fā)人員查看API文檔等。

集成Swagger UI

在項(xiàng)目pom.xml中引入：

<dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.6.1</version>
</dependency>

在此運(yùn)行示例項(xiàng)目，在瀏覽器中輸入：

http://localhost:8080/swagger-ui.html

可以看到如下Web頁(yè)面：

Swagger UI

寫(xiě)在后面

到此你已經(jīng)成功地在項(xiàng)目中集成了Swagger2，接下來(lái)可以使用Springfox的注解進(jìn)行API文檔編寫(xiě)了，詳細(xì)閱讀：

http://springfox.github.io/springfox/docs/current/