springmvc集成swagger2

swagger2有一個web前端ui界面，可以清楚的看到所有被swagger2掃描到的接口列表，源碼在github上：swagger-ui

這個版本不是最新版，但是帶有搜索功能，這是在最新版里沒有的。

項目×××之后，解壓，把dist文件夾下的所有的東西放到項目中靜態目錄下，目錄文件夾名稱假設是swagger，修改index.html文件里的js代碼，源碼里的js訪問doc路徑修改成自己項目的訪問路徑：
url = "/xxx/v2/api-docs";
xxx的部分就是web項目名稱，根據實際情況修改

這個v2/api-docs路徑是swagger2接口文檔的json數據訪問地址，這個地址返回的項目中所有接口說明的json格式字符串，這個index.html中的js代碼就解析這個json數據再渲染出來

項目需要依賴兩個包：

 <dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>${swagger2.version}</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>${swagger-ui.version}</version>
</dependency>
<properties>
<swagger2.version>2.7.0</swagger2.version>
<swagger-ui.version>2.7.0</swagger-ui.version>
</properties>

創建swagger2配置類：

@Configuration // 讓Spring來加載該類配置
@EnableSwagger2 // 啟用Swagger2
@EnableWebMvc
public class Swagger2Config {

    static final Logger log = LoggerFactory.getLogger(Swagger2Config.class);

    @Bean
    public Docket createRestApi() {
        log.info("開始加載Swagger2...");
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select()
                                                      // 掃描指定包中的swagger注解
                                                      .apis(RequestHandlerSelectors.basePackage("com.xxx.xxx.controller"))
                                                      // 掃描所有有注解的api，用這種方式更靈活
                                                      // .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                                                      .paths(PathSelectors.any()).build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder().title("Api Documentation").description("xxx系統API接口文檔").version("1.0.0").build();
    }
}

到此配置文件，啟動項目，訪問地址：http://ip:port/項目名稱/swagger/index.html進入swagger-ui界面，進入后可以看到正在獲取數據，那是解析數據的過程，稍等一會就會顯示出接口列表。

這個接口的json數據來源地址中的域名（也就是ip:port）這個部分是swagger2獲取的web項目啟動的tomcat的域名，有的環境下是會被nginx代理，真正的web服務器域名是不能直接訪問的，這個時候需要添加-Dspringfox.documentation.swagger.v2.host=xxx環境變量，配置nginx的域名，這樣就能正常經過nginx走代理路徑。