Swagger+Spring mvc生成Restful接口文檔

簡介

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

新建工程

咱們新建一個Maven工程，並添加Web Facet，工程結構以下圖所示：

添加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>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>
    
    
    
  
   
 

 
 <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>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接口的說明：

新建Controller

新建一個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;

    /** * 羣組 */
    @ApiModel
    public 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;
        }
    }

好，目前爲止咱們的代碼已經編寫完成，整個工程的目錄結構以下：

爲了讓Swagger可以掃描Spring mvc中定義的Controller，咱們須要在mvc的配置文件裏面定義掃描的路徑和相關的bean：

添加Swagger ui

在GitHub上下載SwaggerUI項目，將dist下全部內容拷貝到本地項目apidoc/web下面，結果目錄以下圖所示：

打開目錄下的index.html文件，找到代碼片斷url = "http://petstore.swagger.io/v2/swagger.json";修改成「/apidoc/v2/api-docs」。
爲了讓網頁顯示中文，咱們能夠取消註釋如下腳本：

爲了可以訪問index.html頁面，咱們在dispatcher-servlet.xml中添加以下配置：

 <!-- Enables swgger ui--><mvc:resources mapping="*.html" location="/"/><mvc:resources mapping="/**" location="/"/>

好，如今咱們啓動tomcat來看看效果：

解決中文亂碼

能夠看到，咱們寫在方法上說明竟然成了亂碼，爲了解決這個問題，咱們新建一個轉換類：

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>
    
    
    
  
   
 

 
 <!-- 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>

咱們再來看看效果:

來源： http://www.cnblogs.com/yuananyun/p/4993426.html

來自爲知筆記(Wiz)