Swagger+ springfox +Spring mvc

简介

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%

时间: 2024-10-01 21:17:50

Swagger+ springfox +Spring mvc的相关文章

Spring MVC中使用Swagger生成API文档和完整项目示例Demo,swagger-server-api

本文作者:小雷FansUnion-一个有创业和投资经验的资深程序员-全球最大中文IT社区CSDN知名博主-排名第119 实际项目中非常需要写文档,提高Java服务端和Web前端以及移动端的对接效率. 听说Swagger这个工具,还不错,就网上找了些资料,自己实践了下. 一:Swagger介绍 Swagger是当前最好用的Restful API文档生成的开源项目,通过swagger-spring项目 实现了与SpingMVC框架的无缝集成功能,方便生成spring restful风格的接口文档,

Configure swagger with spring boot

If you haven’t starting working with spring boot yet, you will quickly find that it pulls out all the common configuration from across your applications. Recently I helped in an effort to modularize configuration and worked on creating a spring-boot-

轻量级 Spring Mvc Api框架

相信大家开发web项目时和别人合作接口联调并不陌生,写完接口了解接口有很多种沟通方法,写wiki,看源代码,写文档等等,当然还有一些比较出名的文档框架如swagger,但是我对swagger的框架并不满意,首先他的引入不够轻量级,其次他对代理bean的支持非常差.于是我自己开发了一套轻量级spring Mvc Api

spring mvc 能过拦截器记录请求数据和响应数据

spring mvc 能过拦截器记录请求数据记录有很多种方式,主要有以下三种: 1:过滤器 2:HandlerInterceptor拦截器 3:Aspect接口控制器 但是就我个人所知要记录返回的数据,只能通过Aspect处理,以下是实现此需要的代码 package com.qmtt.config; import java.util.Arrays; import org.aspectj.lang.ProceedingJoinPoint; import org.aspectj.lang.annot

视图框架:Spring MVC 4.0(1)

目录 一.表单标签库 1.1.简介 1.2.常用属性 1.3.form标签与input标签 1.4.checkbox标签 1.5.radiobutton标签 1.6.password标签 1.7.select标签 1.8.option标签 1.9.options标签 1.10.textarea.errors标签 1.11.hidden标签 1.12.radiobuttons 单选列表与checkboxs复选列表 二.视图解析器 2.1.ViewResolver视图解析器 2.2.链式视图解析器

Spring MVC HTTP请求数据绑定

package com.springmvc.controller; import com.springmvc.model.UserInfo; import org.springframework.core.io.ClassPathResource; import org.springframework.core.io.Resource; import org.springframework.stereotype.Controller; import org.springframework.uti

关于spring mvc的配置文件

1. Web.xml <!--配置页面控制器--> <servlet> <servlet-name>spring</servlet-name> <servlet-class>org.springframework.web.servlet.DispatcherServlet</servlet-class> <init-param> <param-name>contextConfigLocation</par

[转] 使用Spring MVC构建REST风格WEB应用

原文地址:http://fancy888.iteye.com/blog/1629120 对于运行在网络上的MIS系统而言,处理数据的是整个系统的主要任务,翻开程序我们可以看到,80%以上的代码都在处理数据的CRUD操作.采用一种什么样的框架结构,能够使得处理数据的操作变得简单且易理解,这是大部分开发者尤其是架构设计者一直以来思考的一个问题. REST(Representational State Transfer)是一种编程风格,特别是针对网络应用的设计和开发,采用REST可以显著降低开发的复杂

Spring MVC 基础

Spring MVC 基础 1.Web MVC基础 MVC的本质是表现层模式,我们以视图模型为中心,将视图和控制器分离出来.就如同分层模式一样,我们以业务逻辑为中心,把表现层和数据访问层代码分离出来是一样的方法.框架只能在技术层面上给我们帮助,无法在思考和过程上帮助我们,而我们很多人都不喜欢思考和尝试. 2.实现Web MVC的基础 实现Web MVC基础可以概括为1个前段控制器和2个映射. (1)前端控制器FrontController ASP.NET和JSP都是以Page路径和URL一一对应