Swagger+Spring mvc生成Restful接口文档

时间  2019-11-30
标签 swagger+spring swagger spring mvc 生成 restful 接口 文档 栏目 Spring 繁體版
原文   原文链接

简介

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。整体目标是使客户端和文件系统做为服务器以一样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，容许API来始终保持同步。Swagger 让部署管理和使用功能强大的API从未如此简单。
这一次我将从零开始搭建一个工程来演示如何在Spring mvc中整合Swagger生成Restful接口文档。html

新建工程

咱们新建一个Maven工程，并添加Web Facet，工程结构以下图所示：java

新建Maven工程

添加Maven依赖

 
 
 
  
    
    
    
  
   
    
     
     
     
   
    
  1.  <properties>
    2. 
     
     
     
   
    
  2.  <spring.version>4.1.7.RELEASE</spring.version>
    3. 
     
     
     
   
    
  3.  <version.jackson>2.4.4</version.jackson>
    4. 
     
     
     
   
    
  4.  <swagger.version>2.2.2</swagger.version>
    5. 
     
     
     
   
    
  5.  </properties>
    6. 
     
     
     
   
    
    7. 
     
     
     
   
    
  7.  <dependencies>
    8. 
     
     
     
   
    
  8.  <dependency>
    9. 
     
     
     
   
    
  9.  <groupId>org.springframework</groupId>
    10. 
     
     
     
   
    
  10.  <artifactId>spring-webmvc</artifactId>
    11. 
     
     
     
   
    
  11.  <version>${spring.version}</version>
    12. 
     
     
     
   
    
  12.  </dependency>
    13. 
     
     
     
   
    
  13.  <dependency>
    14. 
     
     
     
   
    
  14.  <groupId>org.springframework</groupId>
    15. 
     
     
     
   
    
  15.  <artifactId>spring-core</artifactId>
    16. 
     
     
     
   
    
  16.  <version>${spring.version}</version>
    17. 
     
     
     
   
    
  17.  </dependency>
    18. 
     
     
     
   
    
  18.  <dependency>
    19. 
     
     
     
   
    
  19.  <groupId>com.mangofactory</groupId>
    20. 
     
     
     
   
    
  20.  <artifactId>swagger-springmvc</artifactId>
    21. 
     
     
     
   
    
  21.  <version>1.0.2</version>
    22. 
     
     
     
   
    
  22.  </dependency>
    23. 
     
     
     
   
    
  23.  <dependency>
    24. 
     
     
     
   
    
  24.  <groupId>com.fasterxml.jackson.core</groupId>
    25. 
     
     
     
   
    
  25.  <artifactId>jackson-annotations</artifactId>
    26. 
     
     
     
   
    
  26.  <version>${version.jackson}</version>
    27. 
     
     
     
   
    
  27.  </dependency>
    28. 
     
     
     
   
    
  28.  <dependency>
    29. 
     
     
     
   
    
  29.  <groupId>com.fasterxml.jackson.core</groupId>
    30. 
     
     
     
   
    
  30.  <artifactId>jackson-databind</artifactId>
    31. 
     
     
     
   
    
  31.  <version>${version.jackson}</version>
    32. 
     
     
     
   
    
  32.  </dependency>
    33. 
     
     
     
   
    
  33.  <dependency>
    34. 
     
     
     
   
    
  34.  <groupId>com.fasterxml.jackson.core</groupId>
    35. 
     
     
     
   
    
  35.  <artifactId>jackson-core</artifactId>
    36. 
     
     
     
   
    
  36.  <version>${version.jackson}</version>
    37. 
     
     
     
   
    
  37.  </dependency>
    38. 
     
     
     
   
    
  38.  <dependency>
    39. 
     
     
     
   
    
  39.  <groupId>io.springfox</groupId>
    40. 
     
     
     
   
    
  40.  <artifactId>springfox-swagger2</artifactId>
    41. 
     
     
     
   
    
  41.  <version>${swagger.version}</version>
    42. 
     
     
     
   
    
  42.  </dependency>
    43. 
     
     
     
   
    
  43.  <dependency>
    44. 
     
     
     
   
    
  44.  <groupId>javax.servlet</groupId>
    45. 
     
     
     
   
    
  45.  <artifactId>javax.servlet-api</artifactId>
    46. 
     
     
     
   
    
  46.  <version>3.1.0</version>
    47. 
     
     
     
   
    
  47.  </dependency>
    48. 
     
     
     
   
    
  48.  <!--petstore是官方的一个demo，加入此依赖是为了稍后参考接口描述的编写-->
    49. 
     
     
     
   
    
  49.  <dependency>
    50. 
     
     
     
   
    
  50.  <groupId>io.springfox</groupId>
    51. 
     
     
     
   
    
  51.  <artifactId>springfox-petstore</artifactId>
    52. 
     
     
     
   
    
  52.  <version>${swagger.version}</version>
    53. 
     
     
     
   
    
  53.  </dependency>
    54. 
     
     
     
   
    
    55. 
     
     
     
   
    
  55.  </dependencies>
    56. 
    
    
    
  
   
 

 
 <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启动：git

在工程中的resources文件夹下新建一个spring的文件夹，并新建一个dispatcher-servlet.xml的spring mvc配置文件，添加以下内容：github

添加一个SwaggerConfig类，用于配置Swagger接口的说明：web

新建Controller

新建一个GroupController,并编写测试方法：spring

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的定义以下：typescript

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;
        }
    }

好，目前为止咱们的代码已经编写完成，整个工程的目录结构以下：django

为了让Swagger可以扫描Spring mvc中定义的Controller，咱们须要在mvc的配置文件里面定义扫描的路径和相关的bean：json

添加Swagger ui

在GitHub上下载SwaggerUI项目，将dist下全部内容拷贝到本地项目apidoc/web下面，结果目录以下图所示：api

打开目录下的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配置节：

 
 
 
  
    
    
    
  
   
    
     
     
     
   
    
  1.  <!-- Standard xml based mvc config-->
    2. 
     
     
     
   
    
  2.  <mvc:annotation-driven>
    3. 
     
     
     
   
    
  3.  <mvc:message-converters>
    4. 
     
     
     
   
    
  4.  <bean class="org.springframework.http.converter.StringHttpMessageConverter">
    5. 
     
     
     
   
    
  5.  <property name="supportedMediaTypes">
    6. 
     
     
     
   
    
  6.  <list>
    7. 
     
     
     
   
    
  7.  <value>text/html;charset=UTF-8</value>
    8. 
     
     
     
   
    
  8.  </list>
    9. 
     
     
     
   
    
  9.  </property>
    10. 
     
     
     
   
    
  10.  </bean>
    11. 
     
     
     
   
    
  11.  <bean class="yay.apidoc.converter.MappingJacksonHttpMessageConverterEx"/>
    12. 
     
     
     
   
    
  12.  <bean class="org.springframework.http.converter.ResourceHttpMessageConverter"/>
    13. 
     
     
     
   
    
  13.  </mvc:message-converters>
    14. 
     
     
     
   
    
  14.  </mvc:annotation-driven>
    15. 
    
    
    
  
   
 

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

咱们再来看看效果:




相关文章
相关标签/搜索
每日一句
    每一个你不满意的现在，都有一个你没有努力的曾经。
本站公众号
   欢迎关注本站公众号,获取更多信息
联系我们 最近搜索 最新文章 沪ICP备13005482号-10 MyBatis教程 SQL 教程 MySQL教程 Java 教程 Thymeleaf 教程 Hibernate教程 Spring教程 Redis教程