简介

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>

添加配置

添加一个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 serialization

            SerializationConfig 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);

        }

        @Override

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

我们再来看看效果:

最后提供本次源码下载：
http://files.cnblogs.com/files/yuananyun/Swagger%E4%B8%8ESpring%E7%BB%93%E5%90%88%E7%94%9F%E6%88%90Restful%E6%8E%A5%E5%8F%A3%E6%96%87%E6%A1%A3.rar

仅此而已

最新文章

  1. VirtualBox + CentOS 使用 NAT + Host-Only 方式联网
  2. oracle简历自增序列(转)
  3. mysql &lt;-&gt; sqlite
  4. Xenia and Divisors
  5. mybatis generator with oracle
  6. smarty模板中引用常量没效果
  7. 兼容sdk7&amp;iOS7的issue解决小片段总结
  8. bzoj2342
  9. 关于mysqli 连接数不能正确释放的解决方案
  10. Spring源码解析——如何阅读源码(转)
  11. 安装了VS2010 sp1 后再安装ASP.NET MVC 3.0的问题（Final Result: Installation failed with error code: (0x80070643), &quot;安装时发生严重错误 &quot; (Ela）
  12. JavaEE 对象的串行化（Serialization）
  13. springMVC_05结果跳转方式
  14. 避免 Deepin 15.4 系统 界面卡顿、假死等现象：隐藏自带的“任务栏”，安装轻量级的“任务栏tint2”
  15. nginx set变量后lua无法改值
  16. 解决win10系统无法安装.NET Framework 3.5
  17. final个人阅读作业
  18. Android开发 ---Button的OnClickListener的三种实现方法
  19. php运行代码流程和性能优化方法
  20. Mac OS X 下搭建thrift环境

热门文章

  1. Android自动化测试中AccessibilityService获取控件信息（1）
  2. 术语-服务：IaaS
  3. [转]C# 安装布署
  4. LNMP中常见的502错误及处理方法
  5. [UE4]目标是Pawn、Get Player Character
  6. Quectel module USB driver for linux
  7. 第3章 文件I/O（6）_高级文件操作：文件锁
  8. 第3章 文件I/O（1）_标准C的I/O
  9. 【Unix网络编程】chapter3 套接字编程简介
  10. Android应用程序的自动更新升级（自身升级、通过tomcat）(转)