Spring集成Swagger

1.1  Swagger 是一個簡單、強大的 Restful API 文檔生成管理工具.

　　通過 swagger-spring 項目實現了與 Sping MVC 框架的無縫集成功能，方便生成 spring restful 風格的接口文檔，在項目中集成這個工具，根據我們自己的配置信息能夠自動為我們生成一個 API 文檔展示頁，可以在瀏覽器中直接訪問查看項目的接口信息（如下圖1所示），同時swagger-ui還可以測試spring restful 風格的接口功能，可以對項目提供的每一個 API 接口進行相應的測試。Swagger 生成的 API 文檔是實時更新的，API 接口有任何改動都會在文檔中及時的表現出來。

1.2 項目環境

　　Spring 提供了一個與 Swagger 的集成工具包 springfox，讓 Spring 項目能夠更好的與Swagger 融合，官網提供兩個版本可完成集成：

　　

　　➢   swagger-springmvc 　　　　➢ springfox-swagger2

　　兩種版本配置不同,以最新的springfox-swagger2為例， 項目運行環境：

　　➢   JDK1.8（注：必須使用 JDK1.8 否則 swagger2 無法運行）

　　➢   Spring 4.1.7

　　

　　項目中所需 Maven 依賴：

　　　　➢   springfox-swagger2

　　　　➢   springfox-swagger-ui

　　　　➢   guava

　　　　➢   mapstruct-jdk8

　　　　➢   Jackson

　　　　　　    jackson-core

　　　　　　    jackson-databind     jackson-annotations

 

1.3配置步驟

　　1.3.1  在 pom.xml 文件中添加 Swagger2 相關的依賴，配置（部分）如下

　　

<!--SwaggerUI start-->
        <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>
  <!--SwaggerUI end--> 

　　1.3.2   Swagger2 配置類：SwaggerConfig.java（放入到controller包中）

package com.ytzl.itrip.auth.controller;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.ComponentScan;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.EnableWebMvc;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurationSupport;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;


@EnableSwagger2
//@EnableWebMvc
@ComponentScan("com.ytzl.itrip.auth.controller")
@Configuration //bean
public class SwaggerConfig extends WebMvcConfigurationSupport {
    @Bean
    public Docket createDocket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(getApiInfo())  //api信息
                .select()   //掃描哪個路徑下的哪些API
                .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.any())
                .build();
    }
    private  ApiInfo getApiInfo(){
        return new ApiInfoBuilder()
                .title("標題  xxx項目xxx模塊")
                .contact(new Contact("name","","聯系方式"))
                .version("1.1")
                .build();
    }

}

　　　　

　　　　1> @ComponentScan(basePackages = {"cn.itrip.controller"})：設置 Swagger 掃描包：

　　　　2> @EnableSwagger2： 使 Swagger2 生效

　　　　3> @Configuration：自動在本類上下文加載一些環境變量信息

　　　　4> 創建Docker對象

　　　　　　* Docker apiInfo()：用來創建該API的基本信息，展示在文檔的頁面中（自定義展示的信息） *

　　　　　　* ApiSelectorBuilder select()：設置哪些接口暴露給Swagger展示

　　　　　　* ApiSelectorBuilder apis()：要展示的API apis()

　　　　　　　　** RequestHandlerSelectors.any() 任何路徑

　　　　　　　　** RequestHandlerSelectors.basePackage("com.ustcinfo.*") 包位置

　　　　　　　　* *RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class) 類位置

　　　　　　 * ApiSelectorBuilder paths()：要展示的路徑

　　　　　　　　* *PathSelectors.any()：任何路徑都可以

　　　　　　* Docker build()：創建Docker對象

　　　　5>配置 ApiInfoBuilder（界面顯示）       自定義該API工具展示信息，標題、描述、更新的地址、作者信息、版本等 *

　　　　　　* ApiInfoBuilder title(String str): 設置標題

　　　　　　* ApiInfoBuilder description(String str): 描述

　　　　　　* ApiInfoBuilder termsOfServiceUrl(String str): 更新地址

　　　　　　* ApiInfoBuilder contact(String str): 作者信息

　　　　　　* ApiInfoBuilder version(String str): 版本

　　1.3.3 Spring MVC 配置文件　　

　　　　1> <mvc:default-servlet-handler />：配置對靜態文件的處理方式

<!-- 使用 Swagger Restful API 文檔時，添加此注解 --> 
<mvc:default-servlet-handler /> 

　　　　2> <context:component-scan/>：添加指定掃描(一般情況下不用另寫)

<context:component-scan base-package="cn.itrip.controller"> 
    <context:include-filter type="annotation" expression="org.springframework.stereotype.Controller"/> 
    <context:include-filter type="annotation" expression="org.springframework.context.annotation.Configuration"/> 
    <context:include-filter type="annotation" expression="org.springframework.scheduling.annotation.Scheduled"/> 
</context:component-scan> 

到此准備工作已完成，可以使用了

@Controller
@RequestMapping("/api")
@Api(description = "用戶模塊")
public class ItripUserController {

    @ApiOperation(value = "用戶名的驗證",httpMethod = "GET",produces = "application/json",response = Dto.class,notes = "驗證用戶名是否存在")
    @RequestMapping(value="/ckusr",method = RequestMethod.GET,produces = "application/json")
    @ResponseBody
    public Dto ckusr(@RequestParam("name")
                       @ApiParam(value="用戶賬號",required=true) String name){
}

效果：