一步步完成Maven+SpringMVC+SpringFox+Swagger整合示例

  • 2019 年 10 月 10 日
  • 筆記

本文給出一個整合Maven+SpringMVC+SpringFOX+Swagger的示例，並且一步步給出完成步驟。

一、目標

在做項目的時候，有時候需要提供其它平台（如業務平台）相關的HTTP介面，業務平台則通過開放的HTTP介面獲取相關的內容，並完成自身業務。提供對外開放HTTP API介面，比較常用的是採用Spring MVC來完成。

本文的目標是先搭建一個簡單的Spring MVC應用，然後為Spring MVC整合SpringFox-Swagger以及SpringFox-Swagger-UI，最終，達到Spring MVC對外開放介面API文檔化。

如下圖所示：

二、搭建SpringMVC工程

2.1 新建Maven工程

Eclipse中，File –> New –> Maven Project。

點擊「Next」按鈕， 然後選擇 「maven-archetype-webapp」

繼續點擊「Next」按鈕，然後指定

點擊「Finish」 按鈕結束~ 就這樣，一個簡單的Web工程就建好了。

但是，

默認是使用J2SE-1.5， 配置一下Build Path，使用本地機器上安裝的JDK （本文中使用的是JDK 1.7），工程默認字體是GBK，將其改成UTF-8

完成後，Maven工程的結構如下圖所示：

2.2 引入Spring依賴包

在本示例中，因為簡單，所以只要引入如下幾個jar包就好了。

  <dependencies>      <!--引入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>

完整的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.xxx.tutorial</groupId>    <artifactId>springfox-swagger-demo</artifactId>    <packaging>war</packaging>    <version>0.0.1-SNAPSHOT</version>    <name>springfox-swagger-demo 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>      <!--引入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>springfox-swagger-demo</finalName>    </build>  </project>

2.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.xxx.tutorial" />    <bean      class="org.springframework.web.servlet.mvc.annotation.AnnotationMethodHandlerAdapter" />    </beans>

2.4 配置web.xml

<?xml version="1.0" encoding="UTF-8"?>  <web-app xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"    xmlns="http://java.sun.com/xml/ns/javaee"    xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd"    id="WebApp_ID" metadata-complete="true" version="3.0">    <display-name>Spring MVC</display-name>    <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>/*</url-pattern>    </filter-mapping>  </web-app>

2.5 編寫Controller並測試

配置好spring-mvc.xml以及web.xml文件之後，咱們繼續往下走。

因為，本文Spring MVC示例的作用主要用來暴露對外HTTP API介面，先寫一個簡單的ProductController，其包含一個按照id查詢的方法。

Product.java和ProductController.java的內容如下：

  • Product.java
package com.xxx.tutorial.model;    import java.io.Serializable;    /**   *   * @author wangmengjun   *   */  public class Product implements Serializable {      private static final long serialVersionUID = 1L;      /**ID*/    private Long id;      /**產品名稱*/    private String name;      /**產品型號*/    private String productClass;      /**產品ID*/    private String productId;      /**     * @return the id     */    public Long getId() {      return id;    }      /**     * @param id     *            the id to set     */    public void setId(Long id) {      this.id = id;    }      /**     * @return the name     */    public String getName() {      return name;    }      /**     * @param name     *            the name to set     */    public void setName(String name) {      this.name = name;    }      /**     * @return the productClass     */    public String getProductClass() {      return productClass;    }      /**     * @param productClass     *            the productClass to set     */    public void setProductClass(String productClass) {      this.productClass = productClass;    }      /**     * @return the productId     */    public String getProductId() {      return productId;    }      /**     * @param productId     *            the productId to set     */    public void setProductId(String productId) {      this.productId = productId;    }      /*     * (non-Javadoc)     *     * @see java.lang.Object#toString()     */    @Override    public String toString() {      return "Product [id=" + id + ", name=" + name + ", productClass=" + productClass + ", productId=" + productId          + "]";    }    }
  • ProductController.java
package com.xxx.tutorial.controller;    import org.springframework.http.ResponseEntity;  import org.springframework.web.bind.annotation.PathVariable;  import org.springframework.web.bind.annotation.RequestMapping;  import org.springframework.web.bind.annotation.RequestMethod;  import org.springframework.web.bind.annotation.RestController;    import com.xxx.tutorial.model.Product;    @RestController  @RequestMapping(value = { "/api/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("seven_filters");      product.setProductId("T12345");      return ResponseEntity.ok(product);    }  }

註： 鑒於是一個demo示例，所以沒有寫ProductService以及相關DAO, 直接在方法中返回固定的Product資訊~

2.6 驗證Spring MVC是否ok

完成Controller的程式碼，運行Spring MVC項目，然後，看一下Spring MVC是否運行ok，訪問URL地址

http://localhost:8888/springfox-swagger-demo/api/product/1

  • 出現錯誤

詳細的錯誤資訊如下：

五月 23, 2017 3:00:55 下午 org.apache.catalina.core.StandardWrapperValve invoke  嚴重: Servlet.service() for servlet [spring-mvc] in context with path [/springfox-swagger-demo] threw exception [Request processing failed; nested exception is java.lang.IllegalArgumentException: No converter found for return value of type: class com.xxx.tutorial.model.Product] with root cause  java.lang.IllegalArgumentException: No converter found for return value of type: class com.xxx.tutorial.model.Product    at org.springframework.web.servlet.mvc.method.annotation.AbstractMessageConverterMethodProcessor.writeWithMessageConverters(AbstractMessageConverterMethodProcessor.java:187)    at org.springframework.web.servlet.mvc.method.annotation.HttpEntityMethodProcessor.handleReturnValue(HttpEntityMethodProcessor.java:203)    at org.springframework.web.method.support.HandlerMethodReturnValueHandlerComposite.handleReturnValue(HandlerMethodReturnValueHandlerComposite.java:81)    at org.springframework.web.servlet.mvc.method.annotation.ServletInvocableHandlerMethod.invokeAndHandle(ServletInvocableHandlerMethod.java:132)    at org.springframework.web.servlet.mvc.method.annotation.RequestMappingHandlerAdapter.invokeHandlerMethod(RequestMappingHandlerAdapter.java:827)    at org.springframework.web.servlet.mvc.method.annotation.RequestMappingHandlerAdapter.handleInternal(RequestMappingHandlerAdapter.java:738)    at org.springframework.web.servlet.mvc.method.AbstractHandlerMethodAdapter.handle(AbstractHandlerMethodAdapter.java:85)    at org.springframework.web.servlet.DispatcherServlet.doDispatch(DispatcherServlet.java:963)    at org.springframework.web.servlet.DispatcherServlet.doService(DispatcherServlet.java:897)    at org.springframework.web.servlet.FrameworkServlet.processRequest(FrameworkServlet.java:970)    at org.springframework.web.servlet.FrameworkServlet.doGet(FrameworkServlet.java:861)    at javax.servlet.http.HttpServlet.service(HttpServlet.java:624)    at org.springframework.web.servlet.FrameworkServlet.service(FrameworkServlet.java:846)    at javax.servlet.http.HttpServlet.service(HttpServlet.java:731)    at org.apache.catalina.core.ApplicationFilterChain.internalDoFilter(ApplicationFilterChain.java:303)    at org.apache.catalina.core.ApplicationFilterChain.doFilter(ApplicationFilterChain.java:208)    at org.apache.tomcat.websocket.server.WsFilter.doFilter(WsFilter.java:52)    at org.apache.catalina.core.ApplicationFilterChain.internalDoFilter(ApplicationFilterChain.java:241)    at org.apache.catalina.core.ApplicationFilterChain.doFilter(ApplicationFilterChain.java:208)    at org.springframework.web.filter.CharacterEncodingFilter.doFilterInternal(CharacterEncodingFilter.java:197)    at org.springframework.web.filter.OncePerRequestFilter.doFilter(OncePerRequestFilter.java:107)    at org.apache.catalina.core.ApplicationFilterChain.internalDoFilter(ApplicationFilterChain.java:241)    at org.apache.catalina.core.ApplicationFilterChain.doFilter(ApplicationFilterChain.java:208)    at org.apache.catalina.core.StandardWrapperValve.invoke(StandardWrapperValve.java:220)    at org.apache.catalina.core.StandardContextValve.invoke(StandardContextValve.java:122)    at org.apache.catalina.core.StandardHostValve.invoke(StandardHostValve.java:170)    at org.apache.catalina.valves.ErrorReportValve.invoke(ErrorReportValve.java:103)    at org.apache.catalina.valves.AccessLogValve.invoke(AccessLogValve.java:957)    at org.apache.catalina.core.StandardEngineValve.invoke(StandardEngineValve.java:116)    at org.apache.catalina.connector.CoyoteAdapter.service(CoyoteAdapter.java:423)    at org.apache.coyote.http11.AbstractHttp11Processor.process(AbstractHttp11Processor.java:1079)    at org.apache.coyote.AbstractProtocol$AbstractConnectionHandler.process(AbstractProtocol.java:620)    at org.apache.tomcat.util.net.JIoEndpoint$SocketProcessor.run(JIoEndpoint.java:316)    at java.util.concurrent.ThreadPoolExecutor.runWorker(Unknown Source)    at java.util.concurrent.ThreadPoolExecutor$Worker.run(Unknown Source)    at org.apache.tomcat.util.threads.TaskThread$WrappingRunnable.run(TaskThread.java:61)    at java.lang.Thread.run(Unknown Source)

解決方法，添加jackson-databind依賴包即可

    <dependency>        <groupId>com.fasterxml.jackson.core</groupId>        <artifactId>jackson-databind</artifactId>        <version>2.6.6</version>      </dependency>

重新啟動，運行一下，成功返回資訊，如下圖所示：

為了看的更加清楚，可以使用postman來完成。如：

至此，一個簡單的基於SpringMVC的Web項目已經創建，並能對外提供API介面。

接下來，我們要整合SpringFox和SwaggerUI到該SpringMVC項目中去，使其對外介面文檔化

三、整合SpringFox-Swagger

SpringFox【SpringFox鏈接】已經可以代替Swagger-SpringMVC, 目前SpringFox同時支援Swagger 1.2 和 2.0.

在SpringMVC項目中整合SpringFox-Swagger只要如下幾步即可。

  • 添加SpringFox-Swagger依賴
  • 添加SwaggerConfig

3.1 添加依賴

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

3.2 添加SwaggerConfig

package com.xxx.tutorial.config;    import org.springframework.context.annotation.Bean;  import org.springframework.context.annotation.Configuration;    import springfox.documentation.builders.ApiInfoBuilder;  import springfox.documentation.builders.RequestHandlerSelectors;  import springfox.documentation.service.ApiInfo;  import springfox.documentation.spi.DocumentationType;  import springfox.documentation.spring.web.plugins.Docket;  import springfox.documentation.swagger2.annotations.EnableSwagger2;    @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();    }    }

四、整合SpringFox-Swagger-UI

在SpringMVC項目中整合SpringFox-Swagger-UI也只要如下兩個步驟即可：

  • 添加SpringFox-Swagger-UI依賴
  • 添加配置

4.1 添加依賴

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

4.2 添加配置

在添加配置之前，一起來看一下swagger-ui中使用的靜態資源文件（如 swagger-ui.html ）放在那裡。

spingfox-swagger-ui-2.7.0.jar中的/META-INF/resources/下。 如下圖所示：

為了訪問swagger-ui.html，我們配置對這些靜態資源的訪問。如：

package com.xxx.tutorial.config;    import org.springframework.context.annotation.Configuration;  import org.springframework.web.servlet.config.annotation.EnableWebMvc;  import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;  import org.springframework.web.servlet.config.annotation.WebMvcConfigurerAdapter;    @Configuration  @EnableWebMvc  public class WebAppConfig extends WebMvcConfigurerAdapter {        @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/");      }    }

該配置程式碼的效果和如下程式碼等價：

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

在本文中，可以將其配置在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.xxx.tutorial" />      <bean      class="org.springframework.web.servlet.mvc.annotation.AnnotationMethodHandlerAdapter" />      <mvc:resources mapping="swagger-ui.html" location="classpath:/META-INF/resources/" />    <mvc:resources mapping="/webjars/**"      location="classpath:/META-INF/resources/webjars/" />  </beans>

五、API介面說明程式碼添加並測試

經過上述幾個步驟之後，之前寫的ProductController的介面，就可以實現文檔化了，如本文通過如下的訪問地址訪問：

http://localhost:8888/springfox-swagger-demo/swagger-ui.html

這個介面API雛形出來了，但是還缺少點東西，比如：介面方法的描述等都沒有。修改一下，ProductController.java內容，如：

package com.xxx.tutorial.controller;    import org.springframework.http.ResponseEntity;  import org.springframework.web.bind.annotation.PathVariable;  import org.springframework.web.bind.annotation.RequestMapping;  import org.springframework.web.bind.annotation.RequestMethod;  import org.springframework.web.bind.annotation.RestController;    import com.xxx.tutorial.model.Product;    import io.swagger.annotations.Api;  import io.swagger.annotations.ApiOperation;    @RestController  @RequestMapping(value = { "/api/product/" })  @Api(value = "/product", tags = "Product介面")  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("seven_filters");      product.setProductId("T12345");      return ResponseEntity.ok(product);    }  }

重新訪問，介面已經出現多個我們指定的描述資訊：

在參數id欄中輸入1，然後點擊「try it out」按鈕~ 可以查看介面調用結果~

至此一個簡單的示例就完成了。

六、稍微增加幾個介面

6.1 修改ProductController

package com.xxx.tutorial.controller;    import java.util.Arrays;  import java.util.List;    import org.springframework.http.ResponseEntity;  import org.springframework.web.bind.annotation.PathVariable;  import org.springframework.web.bind.annotation.RequestMapping;  import org.springframework.web.bind.annotation.RequestMethod;  import org.springframework.web.bind.annotation.RestController;    import com.xxx.tutorial.model.Product;    import io.swagger.annotations.Api;  import io.swagger.annotations.ApiOperation;  import io.swagger.annotations.ApiResponse;  import io.swagger.annotations.ApiResponses;    @RestController  @RequestMapping(value = { "/api/product/" })  @Api(value = "/product", tags = "Product介面")  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("seven_filters");      product.setProductId("T12345");      return ResponseEntity.ok(product);    }      @RequestMapping(method = RequestMethod.POST)    @ApiOperation(value = "添加一個新的產品")    @ApiResponses(value = { @ApiResponse(code = 405, message = "參數錯誤") })    public ResponseEntity<String> add(Product product) {      return ResponseEntity.ok("SUCCESS");    }      @RequestMapping(method = RequestMethod.PUT)    @ApiOperation(value = "更新一個產品")    @ApiResponses(value = { @ApiResponse(code = 400, message = "參數錯誤") })    public ResponseEntity<String> update(Product product) {      return ResponseEntity.ok("SUCCESS");    }      @RequestMapping(method = RequestMethod.GET)    @ApiOperation(value = "獲取所有產品資訊", notes = "獲取所有產品資訊", httpMethod = "GET", response = Product.class, responseContainer = "List")    public ResponseEntity<List<Product>> getAllProducts() {      Product product = new Product();      product.setName("七級濾芯凈水器");      product.setId(1L);      product.setProductClass("seven_filters");      product.setProductId("T12345");      return ResponseEntity.ok(Arrays.asList(product, product));    }  }

6.2 swagger-ui展示

由上圖可以看出，不同的method（GET / PUT / POST等）都會以不同的顏色展示出來。 Swagger-ui的添加，可以幫助他人查看介面資訊，並在頁面上進行輸入參數來調用介面~

Maven工程的目錄如下：

本文只是一個簡單的整合示例，大家只要操作一下就能出來結果。

更加詳細的文檔，有興趣的小夥伴可以訪問swagger-ui的官網查看。

VirMach 便宜 VPS

QNews

QNews