SpringMVC、SpringFox和Swagger整合項目實例
目標
在作項目的時候，有時候須要提供其它平臺（如業務平臺）相關的HTTP接口，業務平臺則經過開放的HTTP接口獲取相關的內容，並完成自身業務~html
提供對外開放HTTP API接口，比較經常使用的是採用Spring MVC來完成。前端
本文的目標是先搭建一個簡單的Spring MVC應用，而後爲Spring MVC整合SpringFox-Swagger以及SpringFox-Swagger-UI，最終，達到Spring MVC對外開放接口API文檔化。java
以下圖所示：git
搭建SpringMVC工程
新建Maven工程
Eclipse中，File --> New --> Maven Project， github
點擊「Next」按鈕， 而後選擇 「maven-archetype-webapp」，web
繼續點擊「Next」按鈕，而後指定spring
點擊「Finish」 按鈕結束~ 就這樣，一個簡單的Web工程就建好了~apache
可是，json
默認是使用J2SE-1.5， 配置一下Build Path，使用本地機器上安裝的JDKapi
（本文中使用的是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 /> <!-- 設置使用註解的類所在的jar包 --> <context:component-scan base-package="com.htjf.controller" /> <!--這個是個人項目包結構--> </beans>
配置applicationContext.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:p="http://www.springframework.org/schema/p"
xmlns:context="http://www.springframework.org/schema/context"
xsi:schemaLocation="http://www.springframework.org/schema/beans
http://www.springframework.org/schema/beans/spring-beans-4.3.xsd
http://www.springframework.org/schema/context
http://www.springframework.org/schema/context/spring-context-4.3.xsd">
<!-- 啓用註解掃描，並定義組件查找規則 ，除了@controller，掃描全部的Bean -->
<context:component-scan base-package="com.htjf"/>
<!-- 啓動SpringMVC的註解功能，完成請求和註解POJO的映射 -->
<bean class="org.springframework.web.servlet.mvc.annotation.AnnotationMethodHandlerAdapter" />
<!-- enable autowire 向容器自動註冊 -->
<context:annotation-config />
</beans>
配置web.xml
<?xml version="1.0" encoding="UTF-8"?>
<web-app 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"
version="3.1">
<display-name>Archetype Created Web Application</display-name>
<!-- 利用Spring提供的ContextLoaderListener監聽器去監聽ServletContext對象的建立，並初始化WebApplicationContext對象 -->
<listener>
<listener-class>org.springframework.web.context.ContextLoaderListener</listener-class>
</listener>
<!-- Context Configuration locations for Spring XML files(默認查找/WEB-INF/applicationContext.xml) -->
<context-param>
<param-name>contextConfigLocation</param-name>
<param-value>classpath:applicationContext.xml</param-value>
</context-param>
<!-- 配置Spring MVC的前端控制器：DispatchcerServlet -->
<servlet>
<servlet-name>springmvc</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>springmvc</servlet-name>
<url-pattern>/</url-pattern>
</servlet-mapping>
<!--字符編碼過濾器-->
<filter>
<filter-name>encoding</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>encoding</filter-name>
<url-pattern>/*</url-pattern>
</filter-mapping>
</web-app>
編寫Controller並測試
配置好spring-mvc.xml、applicationContext.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.htjf.config;
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 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
@ComponentScan(basePackages= {"com.htjf.controller"})
@EnableWebMvc
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 文檔") //大標題 title
.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，咱們配置對這些靜態資源的訪問~ 如：
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 />
<!-- 設置使用註解的類所在的jar包 -->
<context:component-scan base-package="com.htjf.controller" />
<mvc:resources location="classpath:/META-INF/resources/" mapping="swagger-ui.html"/>
<mvc:resources location="classpath:/META-INF/resources/webjars/" mapping="/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)
@ApiResponses(value= {
@ApiResponse(code = 400,message="參數錯誤"),
@ApiResponse(code = 401,message="要求用戶的身份認證"),
@ApiResponse(code = 403,message="拒絕執行此請求"),
@ApiResponse(code = 404,message="系統資源未發現"),
@ApiResponse(code = 500,message="系統錯誤"),
@ApiResponse(code = 200,message="成功,其它爲錯誤,返回格式：{code:0,data[{}]},data中的屬性參照下方Model",response=Product.class)})
@ApiOperation(value = "根據id獲取產品信息", notes = "根據id獲取產品信息", httpMethod = "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);
}
@RequestMapping(method = RequestMethod.POST)
@ApiOperation(value = "添加一個新的產品")
@ApiResponses(value = {
@ApiResponse(code = 201,message="已建立。成功請求並建立了新的資源"),
@ApiResponse(code = 401,message="要求用戶的身份認證"),
@ApiResponse(code = 403,message="拒絕執行此請求"),
@ApiResponse(code = 404,message="系統資源未發現"),
@ApiResponse(code = 405, message = "參數錯誤"),
@ApiResponse(code = 200,message="成功,其它爲錯誤,返回格式：{code:0,data[{}]},data中的屬性參照下方Model",response=String.class)})
public ResponseEntity<String> add(Product product) {
return ResponseEntity.ok("SUCCESS");
}
@RequestMapping(method = RequestMethod.PUT)
@ApiOperation(value = "更新一個產品")
@ApiResponses(value = {
@ApiResponse(code = 200,message="成功,其它爲錯誤,返回格式：{code:0,data[{}]},data中的屬性參照下方Model",response=String.class),
@ApiResponse(code = 201,message="已建立。成功請求並建立了新的資源"),
@ApiResponse(code = 400, message = "參數錯誤"),
@ApiResponse(code = 401,message="要求用戶的身份認證"),
@ApiResponse(code = 403,message="拒絕執行此請求"),
@ApiResponse(code = 404,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));
}
}
@RequestMapping(method=RequestMethod.DELETE)
@ApiOperation(value="刪除某個產品信息",notes="刪除某個產品信息")
/* @ApiImplicitParams(@ApiImplicitParam(name="carOwnerName",value="產品id",dataType="Long"))*/
@ApiResponses(value= {
@ApiResponse(code = 204,message="無內容。服務器成功處理，但未返回內容！"),
@ApiResponse(code = 400,message="參數錯誤"),
@ApiResponse(code = 401,message="要求用戶的身份認證"),
@ApiResponse(code = 403,message="拒絕執行此請求"),
@ApiResponse(code = 500,message="系統錯誤"),
@ApiResponse(code = 200,message="成功,其它爲錯誤,返回格式：{code:0,data[{}]},data中的屬性參照下方Model",response=String.class)})
public ResponseEntity<String> delete(@PathVariable Long id){
if(carOwnerName==null) {
return new ResponseEntity<String>(HttpStatus.NO_CONTENT);
}else {
return ResponseEntity.ok("SUCCESS");
}
}
swagger-ui展現
由上圖能夠看出，不一樣的method（GET / PUT / POST等）都會以不一樣的顏色展現出來~
Swagger-ui的添加，能夠幫助他人查看接口信息，並在頁面上進行輸入參數來調用接口~
Maven工程的目錄以下：
本文只是一個簡單的整合示例，你們只要操做一下就能出來結果。
接下來說解Swagger 經常使用註解使用
--@Api()用於類;
表示這個類是一個swagger的資源。它有兩個屬性，分別是：
String value();---也是說明，可使用tags替代
String[] tags();---是一個數組，表示說明，tags若是有多個值，會生成多個list；
例如：
@Api(value="用戶controller",tags={"用戶操做接口"})
@RestController
public class UserController {
}
ui效果圖：
--@ApiOperation()用於方法；
表示一個http請求的操做 ,它有4個經常使用屬性：
String value();--用於方法描述；
String notes();--用於提示內容
String[] tags();--能夠從新分組（視狀況而用）
String httpMethod(); --請求方法類型，例如：httpMethod=「GET」;
--@ApiParam() 用於方法，參數，字段說明；表示對參數的添加元數據（說明或是否必填等） ,它有幾個經常使用參數：
String name();--參數名
String value();--參數說明
boolean required();--是否必填
boolean allowEmptyValue();--是否容許有空值
例如：
@Api(value="用戶controller",tags={"用戶操做接口"})
@RestController
public class UserController {
@ApiOperation(value="獲取用戶信息",tags={"獲取用戶信息copy"},notes="注意問題點")
@GetMapping("/getUserInfo")
public User getUserInfo(@ApiParam(name="id",value="用戶id",required=true) Long id,@ApiParam(name="username",value="用戶名") String username) {
// userService可忽略，是業務邏輯
User user = userService.getUserInfo();
return user;
}
}
ui效果圖：
--@ApiModel()用於類 ；表示對類進行說明，用於參數用實體類接收
value–表示對象名
description–描述
均可省略
--@ApiModelProperty()用於方法，字段； 表示對model屬性的說明或者數據操做更改
value–字段說明
name–重寫屬性名字
dataType–重寫屬性類型
required–是否必填
example–舉例說明
hidden–隱藏
例如：
@ApiModel(value="user對象",description="用戶對象user")
public class User implements Serializable{
private static final long serialVersionUID = 1L;
@ApiModelProperty(value="用戶名",name="username",example="xingguo")
private String username;
@ApiModelProperty(value="狀態",name="state",required=true)
private Integer state;
private String password;
private String nickName;
private Integer isDeleted;
@ApiModelProperty(value="id數組",hidden=true)
private String[] ids;
private List<String> idList;
//省略get/set
}
@ApiOperation("更改用戶信息")
@PostMapping("/updateUserInfo")
public int updateUserInfo(@RequestBody @ApiParam(name="用戶對象",value="傳入json格式",required=true) User user){
//注意，必定要添加@RequestBody註解
int num = userService.updateUserInfo(user);
return num;
}
ui效果圖：
--@ApiIgnore()用於類或者方法上，能夠不被swagger顯示在頁面上
比較簡單, 這裏不作舉例
--@ApiImplicitParam() 用於方法
表示單獨的請求參數
@ApiImplicitParams() 用於方法，包含多個 @ApiImplicitParam
name–參數ming
value–參數說明
dataType–數據類型
paramType–參數類型
example–舉例說明
*****在controller層使用@RequestParam的時候，發現這個參數是必需要輸入值的，可是咱們有時候必須查詢的時候容許參數爲空，使用這個註解就不行了。可是使用@ApiImplicitParam這個註解能夠解決這個問題。
例如：
@ApiOperation("查詢測試")
@GetMapping("select")
//@ApiImplicitParam(name="name",value="用戶名",dataType="String", paramType = "query")
@ApiImplicitParams({
@ApiImplicitParam(name="name",value="用戶名",dataType="string", paramType = "query",example="xingguo"),
@ApiImplicitParam(name="id",value="用戶id",dataType="long", paramType = "query")})
public void select(){
}
ui效果圖：
更加詳細的文檔，有興趣的小夥伴能夠訪問swagger-ui的官網查看~
相關文章
- 1. Maven+SpringMVC+SpringFox+Swagger整合示例
- 2. Swagger與SpringMVC項目整合
- 3. 一步步完成Maven+SpringMVC+SpringFox+Swagger整合示例
- 4. springMvc+swagger整合例子
- 5. SPRINGMVC+SWAGGER整合例子
- 6. springmvc輕鬆整合springfox
- 7. springfox-swagger2 2.6.1 整合springmvc 3.2
- 8. Springfox與swagger的整合使用
- 9. SpringMVC與Swagger 整合
- 10. springfox-swagger2 springfox-swagger-ui
- 更多相關文章...
- • Thymeleaf項目實踐 - Thymeleaf 教程
- • MyBatis與Spring的整合實例 - MyBatis教程
- • TiDB 在摩拜單車在線數據業務的應用和實踐
- • IntelliJ IDEA 代碼格式化配置和快捷鍵
相關標籤/搜索
每日一句
-
每一个你不满意的现在，都有一个你没有努力的曾经。
最新文章
歡迎關注本站公眾號,獲取更多信息
相關文章
- 1. Maven+SpringMVC+SpringFox+Swagger整合示例
- 2. Swagger與SpringMVC項目整合
- 3. 一步步完成Maven+SpringMVC+SpringFox+Swagger整合示例
- 4. springMvc+swagger整合例子
- 5. SPRINGMVC+SWAGGER整合例子
- 6. springmvc輕鬆整合springfox
- 7. springfox-swagger2 2.6.1 整合springmvc 3.2
- 8. Springfox與swagger的整合使用
- 9. SpringMVC與Swagger 整合
- 10. springfox-swagger2 springfox-swagger-ui