Swagger+Spring mvc生成Restful接口文檔

2019獨角獸企業重金招聘Python工程師標準>>>

Swagger?是一個規范和完整的框架，用于生成、描述、調用和可視化 RESTful 風格的 Web 服務。總體目標是使客戶端和文件系統作為服務器以同樣的速度來更新。文件的方法，參數和模型緊密集成到服務器端的代碼，允許API來始終保持同步。Swagger 讓部署管理和使用功能強大的API從未如此簡單。
這一次我將從零開始搭建一個工程來演示如何在Spring mvc中整合Swagger生成Restful接口文檔。

添加Maven依賴

 <properties><spring.version>4.1.7.RELEASE</spring.version><version.jackson>2.4.4</version.jackson><swagger.version>2.2.2</swagger.version></properties><dependencies><dependency><groupId>org.springframework</groupId><artifactId>spring-webmvc</artifactId><version>${spring.version}</version></dependency><dependency><groupId>org.springframework</groupId><artifactId>spring-core</artifactId><version>${spring.version}</version></dependency><dependency><groupId>com.mangofactory</groupId><artifactId>swagger-springmvc</artifactId><version>1.0.2</version></dependency><dependency><groupId>com.fasterxml.jackson.core</groupId><artifactId>jackson-annotations</artifactId><version>${version.jackson}</version></dependency><dependency><groupId>com.fasterxml.jackson.core</groupId><artifactId>jackson-databind</artifactId><version>${version.jackson}</version></dependency><dependency><groupId>com.fasterxml.jackson.core</groupId><artifactId>jackson-core</artifactId><version>${version.jackson}</version></dependency><dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger2</artifactId><version>${swagger.version}</version></dependency><dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger-ui</artifactId><version>2.5.0</version></dependency><dependency><groupId>javax.servlet</groupId><artifactId>javax.servlet-api</artifactId><version>3.1.0</version></dependency><!--petstore是官方的一個demo，加入此依賴是為了稍后參考接口描述的編寫--><dependency><groupId>io.springfox</groupId><artifactId>springfox-petstore</artifactId><version>${swagger.version}</version></dependency></dependencies>

添加配置

添加一個ApplicationInitializer類，用于配置DispatchServlet啟動：

在工程中的resources文件夾下新建一個spring的文件夾，并新建一個dispatcher-servlet.xml的spring mvc配置文件，添加如下內容：

添加一個SwaggerConfig類，用于配置Swagger接口的說明：

package com.bbd.liangdian.config;import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
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;/*** Created by Administrator on 2017/3/6.*/
@EnableSwagger2
@Configuration
public class SwaggerConfig {@Beanpublic Docket createRestApi() {return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select().apis(RequestHandlerSelectors.basePackage("com.bbd.liangdian.apis")).paths(PathSelectors.any()).build();}private ApiInfo apiInfo() {return new ApiInfoBuilder().title("量點項目API文檔").version("1.0").description("1:量點API,根據分組查找所需要的API.<br /> 2:注意請求的方法定義.").build();}
}

新建一個GroupController,并編寫測試方法：

    package yay.apidoc.controller;import io.swagger.annotations.*;import org.springframework.stereotype.Controller;import org.springframework.web.bind.annotation.RequestBody;import org.springframework.web.bind.annotation.RequestMapping;import org.springframework.web.bind.annotation.RequestMethod;import yay.apidoc.model.UamGroup;import java.util.LinkedList;import java.util.List;/*** Created by yuananyun on 2015/11/23.*/@Controller@RequestMapping(value = "/group", produces = {"application/json;charset=UTF-8"})@Api(value = "/group", description = "群組的相關操作")public class GroupController {@RequestMapping(value = "addGroup", method = RequestMethod.PUT)@ApiOperation(notes = "addGroup", httpMethod = "POST", value = "添加一個新的群組")@ApiResponses(value = {@ApiResponse(code = 405, message = "invalid input")})public UamGroup addGroup(@ApiParam(required = true, value = "group data") @RequestBody UamGroup group) {return group;}@RequestMapping(value = "getAccessibleGroups", method = RequestMethod.GET)@ApiOperation(notes = "getAccessibleGroups", httpMethod = "GET", value = "獲取我可以訪問的群組的列表")public List<UamGroup> getAccessibleGroups() {UamGroup group1 = new UamGroup();group1.setGroupId("1");group1.setName("testGroup1");UamGroup group2 = new UamGroup();group2.setGroupId("2");group2.setName("testGroup2");List<UamGroup> groupList = new LinkedList<UamGroup>();groupList.add(group1);groupList.add(group2);return groupList;}}

其中UamGroup的定義如下：

    package yay.apidoc.model;import io.swagger.annotations.ApiModel;import io.swagger.annotations.ApiModelProperty;/*** 群組*/@ApiModelpublic class UamGroup {/*** 編號*/@ApiModelProperty(value = "群組的Id", required = true)private String groupId;/*** 名稱*/@ApiModelProperty(value = "群組的名稱", required = true)private String name;/*** 群組圖標*/@ApiModelProperty(value = "群組的頭像", required = false)private String icon;public String getGroupId() {return groupId;}public void setGroupId(String groupId) {this.groupId = groupId;}public String getName() {return name;}public void setName(String name) {this.name = name;}public String getIcon() {return icon;}public void setIcon(String icon) {this.icon = icon;}}

配置web.xml

<?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns="http://java.sun.com/xml/ns/javaee"xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"xsi:schemaLocation="http://java.sun.com/xml/ns/javaeehttp://java.sun.com/xml/ns/javaee/web-app_3_0.xsd"version="3.0"><display-name>Archetype Created Web Application</display-name><context-param><!-- 配置 spring 容器啟動的配置文件的路徑 --><param-name>contextConfigLocation</param-name><param-value>classpath:applicationContext.xml</param-value></context-param><context-param><param-name>logbackConfigLocation</param-name><param-value>classpath:logback.xml</param-value></context-param><listener><listener-class>ch.qos.logback.ext.spring.web.LogbackConfigListener</listener-class></listener><listener><listener-class>org.springframework.web.context.ContextLoaderListener</listener-class></listener><!-- 配置編碼過濾器 --><filter><filter-name>CharacterEncodingFilter</filter-name><filter-class>org.springframework.web.filter.CharacterEncodingFilter</filter-class><async-supported>true</async-supported><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>CharacterEncodingFilter</filter-name><url-pattern>/*</url-pattern></filter-mapping><servlet><servlet-name>DispatcherServlet</servlet-name><servlet-class>org.springframework.web.servlet.DispatcherServlet</servlet-class><!-- 配置tomcat啟動時 啟動SpringMVC --><init-param><param-name>contextConfigLocation</param-name><param-value>classpath:applicationContext-mvc.xml</param-value></init-param><load-on-startup>1</load-on-startup><async-supported>true</async-supported></servlet><servlet-mapping><servlet-name>DispatcherServlet</servlet-name><url-pattern>/</url-pattern></servlet-mapping><!-- 配置swagger-ui --><servlet-mapping><servlet-name>default</servlet-name><url-pattern>/swagger-ui.html</url-pattern></servlet-mapping><welcome-file-list><welcome-file>index.html</welcome-file></welcome-file-list><error-page><error-code>404</error-code><location>/index.html</location></error-page>
</web-app>

好，現在我們啟動tomcat來看看效果： localhost:8080/swagger-ui.html

解決中文亂碼

可以看到，我們寫在方法上說明居然成了亂碼，為了解決這個問題，我們新建一個轉換類：

    package yay.apidoc.converter;import com.fasterxml.jackson.annotation.JsonInclude;import com.fasterxml.jackson.databind.*;import org.springframework.http.HttpInputMessage;import org.springframework.http.converter.HttpMessageNotReadableException;import org.springframework.http.converter.json.MappingJackson2HttpMessageConverter;import java.io.IOException;import java.text.SimpleDateFormat;/*** Created by yuananyun on 2015/11/23.*/public class MappingJacksonHttpMessageConverterEx extends MappingJackson2HttpMessageConverter {private ObjectMapper objectMapper = new ObjectMapper();public MappingJacksonHttpMessageConverterEx() {super();DeserializationConfig deserializationConfig = objectMapper.getDeserializationConfig().without(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES);objectMapper.setConfig(deserializationConfig);// Configure serializationSerializationConfig serializationConfig = objectMapper.getSerializationConfig().without(SerializationFeature.FAIL_ON_EMPTY_BEANS);//serializationConfig.withDateFormat(new SimpleDateFormat("yyyy-MM-dd HH:mm:ss"));objectMapper.setConfig(serializationConfig);objectMapper.setDateFormat(new SimpleDateFormat("yyyy-MM-dd HH:mm:ss"));objectMapper.setSerializationInclusion(JsonInclude.Include.NON_NULL);//        objectMapper.configure(SerializationFeature.WRITE_DATES_AS_TIMESTAMPS, true);objectMapper.configure(SerializationFeature.ORDER_MAP_ENTRIES_BY_KEYS,true);setObjectMapper(objectMapper);}@Overrideprotected Object readInternal(Class<?> clazz, HttpInputMessage inputMessage)throws IOException, HttpMessageNotReadableException {JavaType javaType = getJavaType(null, clazz);return this.objectMapper.readValue(inputMessage.getBody(), javaType);}}

然后修改dispatcher-servlet.xml中的mvc:annotation-driven配置節：

        <!-- Standard xml based mvc config--><mvc:annotation-driven><mvc:message-converters><bean class="org.springframework.http.converter.StringHttpMessageConverter"><property name="supportedMediaTypes"><list><value>text/html;charset=UTF-8</value></list></property></bean><bean class="yay.apidoc.converter.MappingJacksonHttpMessageConverterEx"/><bean class="org.springframework.http.converter.ResourceHttpMessageConverter"/></mvc:message-converters></mvc:annotation-driven>

我們再來看看效果:?localhost:8080/swagger-ui.html