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

時間  2019-11-26
標籤 步步 完成 maven+springmvc+springfox+swagger maven springmvc springfox swagger 整合 示例 欄目 Maven 简体版
原文   原文鏈接

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

本人在作實例時發現 http://blog.csdn.net/zth1002/article/details/46927187 中，Spring必須是4.0以上版本。java

目標

在作項目的時候，有時候須要提供其它平臺（如業務平臺）相關的HTTP接口，業務平臺則經過開放的HTTP接口獲取相關的內容，並完成自身業務~git

提供對外開放HTTP API接口，比較經常使用的是採用Spring MVC來完成。github

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

以下圖所示：spring

搭建SpringMVC工程

新建Maven工程

Eclipse中，File --> New --> Maven Project，apache

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

繼續點擊「Next」按鈕，而後指定spring-mvc

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

可是，

默認是使用J2SE-1.5， 配置一下Build Path，使用本地機器上安裝的JDK

（本文中使用的是JDK 1.7），工程默認字體是GBK，將其改爲UTF-8

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

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

編寫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>

配置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>

編寫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信息~

驗證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

添加依賴

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

添加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依賴
  • 添加配置

添加依賴

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

添加配置

在添加配置以前，一塊兒來看一下swagger-ui中使用的靜態資源文件（如**swagger-ui.html **）放在那裏~

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

爲了訪問swagger-ui.html，咱們配置對這些靜態資源的訪問~ 如：

該配置代碼的效果和以下代碼等價~

<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」按鈕~ 能夠查看接口調用結果~

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

稍微增長几個接口

修改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));
	}
}

swagger-ui展現

由上圖能夠看出，不一樣的method（GET / PUT / POST等）都會以不一樣的顏色展現出來~

Swagger-ui的添加，能夠幫助他人查看接口信息，並在頁面上進行輸入參數來調用接口~

Maven工程的目錄以下：

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

更加詳細的文檔，有興趣的小夥伴能夠訪問swagger-ui的官網查看~

相關文章
相關標籤/搜索
每日一句
    每一个你不满意的现在，都有一个你没有努力的曾经。
本站公眾號
   歡迎關注本站公眾號,獲取更多信息
聯繫我們 最近搜索 最新文章 沪ICP备13005482号-10 MyBatis教程 SQL 教程 MySQL教程 Java 教程 Thymeleaf 教程 Hibernate教程 Spring教程 Redis教程