spring3.2 內建swagger 2.0.1

項目中需要開放接口供對接方調試，需要簡單的web界面，故選擇SpringMVC進行HTTP接口開發，SwaggerUI作為使用者界面，做接口調用。 

一、搭建SpringMVC工程 

1、建立maven工程 

具體見另一篇文章：https://blog.csdn.net/eleanoryss/article/details/80001890 

建立成功之後的maven工程如下： 

2、加入Spring依賴 

本示例很簡單，是以引入幾個jar包即可，完整的pom.xml檔案内容如下：

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

  xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">

  <modelVersion>4.0.0</modelVersion>

  <groupId>com.maven.example.web</groupId>

  <artifactId>swagger-rocketmq</artifactId>

  <packaging>war</packaging>

  <version>0.0.1-SNAPSHOT</version>

  <name>swagger-rocketmq Maven Webapp</name>

  <url>http://maven.apache.org</url>

    <properties>

        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>

        <spring.framework.version>4.3.6.RELEASE</spring.framework.version>

    </properties>

  <dependencies>

    <!-- ********************jackson******************************* -->  

    <dependency>

        <groupId>com.fasterxml.jackson.core</groupId>

        <artifactId>jackson-databind</artifactId>

        <version>2.8.9</version>

    </dependency>   

    <!-- ********************Spring依賴********************* -->

    <dependency>

            <groupId>org.springframework</groupId>

            <artifactId>spring-core</artifactId>

            <version>${spring.framework.version}</version>

    </dependency>

    <dependency>

            <groupId>org.springframework</groupId>

            <artifactId>spring-context</artifactId>

            <version>${spring.framework.version}</version>

    </dependency>

    <dependency>

            <groupId>org.springframework</groupId>

            <artifactId>spring-webmvc</artifactId>

            <version>${spring.framework.version}</version>

    </dependency>  

  </dependencies>

  <build>

    <finalName>swagger-rocketmq</finalName>

  </build>

</project>

3、編寫spring-mvc.xml檔案

<?xml version="1.0" encoding="UTF-8"?>

<beans xmlns="http://www.springframework.org/schema/beans"

    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:context="http://www.springframework.org/schema/context"

    xmlns:mvc="http://www.springframework.org/schema/mvc" xmlns:p="http://www.springframework.org/schema/p"

    xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-4.0.xsd

        http://www.springframework.org/schema/context http://www.springframework.org/schema/context/spring-context-4.0.xsd

        http://www.springframework.org/schema/mvc http://www.springframework.org/schema/mvc/spring-mvc-4.0.xsd">

    <!-- 預設的注解映射的支援 ,它會自動注冊DefaultAnnotationHandlerMapping 與AnnotationMethodHandlerAdapter -->

    <mvc:annotation-driven />

    <!-- enable autowire 向容器自動注冊 -->

    <context:annotation-config />

    <!-- 設定使用注解的類所在的jar包 -->

    <context:component-scan base-package="com.swagger" />   

    <bean

        class="org.springframework.web.servlet.mvc.annotation.AnnotationMethodHandlerAdapter" />

    <!-- 掃描類包，将标注Spring注解的類自動轉化Bean，同時完成Bean的注入 -->

    <bean name="propertyConfigure"

        class="org.springframework.beans.factory.config.PropertyPlaceholderConfigurer">

        <property name="locations">

            <list>

                <value>classpath:configInfo.properties</value>

            </list>

        </property>

    </bean>   

</beans>

4、配置web.xml

<?xml version="1.0" encoding="UTF-8"?>

<web-app version="3.1"

    xmlns="http://xmlns.jcp.org/xml/ns/javaee" 

    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

    xsi:schemaLocation="http://xmlns.jcp.org/xml/ns/javaee http://xmlns.jcp.org/xml/ns/javaee/web-app_3_1.xsd">

  <display-name>Archetype Created Web Application</display-name>

    <!-- Spring MVC 核心控制器 DispatcherServlet 配置-->

    <servlet>

        <servlet-name>spring-mvc</servlet-name>

        <servlet-class>org.springframework.web.servlet.DispatcherServlet</servlet-class>

        <init-param>

            <param-name>contextConfigLocation</param-name>

            <param-value>classpath:spring-mvc.xml</param-value>

        </init-param>

        <load-on-startup>1</load-on-startup>

        <async-supported>true</async-supported>

    </servlet>

    <servlet-mapping>

        <servlet-name>spring-mvc</servlet-name>

        <url-pattern>/</url-pattern>

    </servlet-mapping>  

    <!--   配置編碼格式過濾器 -->    

    <filter>

        <filter-name>encodingFilter</filter-name>

        <filter-class>org.springframework.web.filter.CharacterEncodingFilter</filter-class>

        <init-param>

            <param-name>encoding</param-name>

            <param-value>UTF-8</param-value>

        </init-param>

        <init-param>

            <param-name>forceEncoding</param-name>

            <param-value>true</param-value>

        </init-param>

    </filter>

    <filter-mapping>

        <filter-name>encodingFilter</filter-name>

        <url-pattern>

    private Long id;

    private String name;

    private String productClass;

    private String productId;

    public Long getId() {

        return id;

    }

    public void setId(Long id) {

        this.id = id;

    }

    public String getName() {

        return name;

    }

    public void setName(String name) {

        this.name = name;

    }

    public String getProductClass() {

        return productClass;

    }

    public void setProductClass(String productClass) {

        this.productClass = productClass;

    }

    public String getProductId() {

        return productId;

    }

    public void setProductId(String productId) {

        this.productId = productId;

    }

    @Override

    public String toString() {

        return "Product [id=" + id + ", name=" + name + ", productClass=" + productClass + ", productId=" + productId + "]";

    }

}

HTTP查詢接口：ProductController.java

@RestController

@RequestMapping(value = { "/product/"})

public class ProductController {

    @RequestMapping(value = "/{id}", method = RequestMethod.GET)

    public ResponseEntity<Product> get(@PathVariable Long id) {

        Product product = new Product();

        product.setName("空氣淨化器");

        product.setId(1L);

        product.setProductClass("filters");

        product.setProductId("T12345");

        return ResponseEntity.ok(product);

    }

}

在方法中直接傳回的寫死的資料，因為隻是一個示例代碼。 

6、驗證該端口能否通路 

在本地Tomcat運作該工程，通路如下位址： 

http://localhost:8080/swagger-rocketmq/product/1/ 

成功傳回資訊 

至此，我們完成了一個簡單的web接口。

二、引入SwaggerUI 

1、加入SpringFox-Swagger依賴

<!-- swagger2核心依賴 -->

        <dependency>

            <groupId>io.springfox</groupId>

            <artifactId>springfox-swagger2</artifactId>

            <version>2.7.0</version>

        </dependency>

2、加入SpringFox-Swagger-UI依賴

<!-- swagger-ui為項目提供api展示及測試的界面 -->

        <dependency>

            <groupId>io.springfox</groupId>

            <artifactId>springfox-swagger-ui</artifactId>

            <version>2.7.0</version>

        </dependency>

3、添加SwaggerConfig

@Configuration

@EnableSwagger2

public class SwaggerConfig {

    @Bean

    public Docket api() {

        return new Docket(DocumentationType.SWAGGER_2)

                .select()

                .apis(RequestHandlerSelectors.any())

                .build()

                .apiInfo(apiInfo());

    }

    private ApiInfo apiInfo() {

        return new ApiInfoBuilder()

                .title("開放接口API")

                .description("HTTP對外開放接口")

                .version("1.0.0")

                .termsOfServiceUrl("http://xxx.xxx.com")

                .license("LICENSE")

                .licenseUrl("http://xxx.xxx.com")

                .build();

    }

}

4、配置通路swaggerUI靜态資源 

swagger-ui中使用的靜态資源檔案（如 swagger-ui.html ）放在spingfox-swagger-ui-2.7.0.jar中的/META-INF/resources/下： 

在spring-mvc.xml檔案中加入如下配置：

    <mvc:resources mapping="swagger-ui.html" location="classpath:/META-INF/resources/" />

    <mvc:resources mapping="/webjars/**"

        location="classpath:/META-INF/resources/webjars/" />

三、添加API接口說明 

1、在ProductController.java中加入注釋

@RestController

@RequestMapping(value = { "/product/"})

@Api(value = "/ProductController", tags = "接口開放示例")

public class ProductController {

    @RequestMapping(value = "/{id}", method = RequestMethod.GET)

    @ApiOperation(value = "根據id擷取産品資訊", notes = "根據id擷取産品資訊", httpMethod = "GET", response = Product.class)

    public ResponseEntity<Product> get(@PathVariable Long id) {

        Product product = new Product();

        product.setName("空氣淨化器");

        product.setId(1L);

        product.setProductClass("filters");

        product.setProductId("T12345");

        return ResponseEntity.ok(product);

    }

}

2、通路如下位址： 

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

頁面如下： 

在參數id欄中輸入任意數字1，然後點選Try it out，可檢視接口調用結果，結果如下： 

至此，SpringMVC整合SwaggerUI的執行個體就完成了。

上面涉及到的知識點簡單介紹：

1、swagger 

swagger可以根據業務代碼自動生成相關的api接口文檔，尤其用于restful風格中的項目，開發人員幾乎可以不用專門去維護rest api，這個架構可以自動為你的業務代碼生成restfut風格的api，而且還提供相應的測試界面，自動顯示json格式的響應。大大友善了背景開發人員與前端的溝通與聯調成本。

2、SpringFox-swagger 

spring充分利用自已的優勢，把swagger內建到自己的項目裡，整了一個spring-swagger，後來便演變成springfox。springfox本身隻是利用自身的aop的特點，通過plug的方式把swagger內建了進來，它本身對業務api的生成，還是依靠swagger來實作。

3、SpringFox 

SpringFox的大緻原理是：在項目啟動時，spring上下文在初始化的過程，架構自動跟據配置加載一些swagger相關的bean到目前的上下文中，并自動掃描系統中可能需要生成api文檔那些類，并生成相應的資訊緩存起來。如果項目MVC控制層用的是springMvc那麼會自動掃描所有Controller類，跟據這些Controller類中的方法生成相應的api文檔。

參考： 

https://my.oschina.net/wangmengjun/blog/907679 

https://blog.csdn.net/w4hechuan2009/article/details/68892718

實際合入SpringMVC後出現的問題： 

1、隻有某些類需要開放給第三方調用或者調試，其他接口在SwaggerUI中不可見 

解決辦法： 

在SwaggerConfig.java中修改： 

将RequestHandlerSelectors.any()修改為RequestHandlerSelectors.withClassAnnotation(Api.class)，可以選擇隻顯示添加了@Api注釋的類。

@Bean

public Docket api() {

return new Docket(DocumentationType.SWAGGER_2)

.select()

.apis(RequestHandlerSelectors.withClassAnnotation(Api.class))

.build()

.apiInfo(apiInfo());

    }