springMVC集成springfox和swagger实现接口文档管理

在项目开发过程中，编写接口文档时常对开发人员来说是一件耗时费力的事情。因为不论是先写文档或者是后期补充文档都是一件令人烦恼的事情。

但是，自从swagger UI诞生之后，这件事情将变得简单。在开发人员编写程序的过程中，不必在劳心费神接口api的编写，因为现在是在开发的同时完成了文档编写工作，仅仅几个注解便可以搞定。下面就来看看在spring项目中使用swagger的示例。

一、以下使用已经集成swagger ui静态资源的springfox组件。具体pom配置如下：

<dependency>

<groupId>com.mangofactory</groupId>

<artifactId>swagger-springmvc</artifactId>

<version>1.0.2</version>

</dependency>

<dependency>

<groupId>io.springfox</groupId>

<artifactId>springfox-swagger2</artifactId>

<version>2.6.1</version>

</dependency>

<dependency>

<groupId>io.springfox</groupId>

<artifactId>springfox-swagger-ui</artifactId>

<version>2.6.1</version>

</dependency>

<dependency>

<groupId>com.fasterxml.jackson.core</groupId>

<artifactId>jackson-databind</artifactId>

<version>2.8.7</version>

</dependency>

<dependency>

<groupId>com.fasterxml.jackson.core</groupId>

<artifactId>jackson-annotations</artifactId>

<version>2.8.5</version>

</dependency>

<dependency>

<groupId>com.fasterxml.jackson.core</groupId>

<artifactId>jackson-core</artifactId>

<version>2.8.7</version>

</dependency>

二、编写swagger的配置类，具体如下：

package com.mark.util;



import com.mangofactory.swagger.configuration.SpringSwaggerConfig;

import com.mangofactory.swagger.models.dto.ApiInfo;

import com.mangofactory.swagger.plugin.EnableSwagger;

import com.mangofactory.swagger.plugin.SwaggerSpringMvcPlugin;

import org.springframework.beans.factory.annotation.Autowired;

import org.springframework.context.annotation.Bean;

import org.springframework.context.annotation.ComponentScan;

import org.springframework.context.annotation.Configuration;

import org.springframework.web.servlet.config.annotation.EnableWebMvc;

import springfox.documentation.spi.DocumentationType;

import springfox.documentation.spring.web.plugins.Docket;

import springfox.documentation.swagger2.annotations.EnableSwagger2;





/**

* swagger配置文件

*

* @author maliqiang

* @version 1.0

* @create 2017-03-14

*/

@Configuration

//@EnableWebMvc

@EnableSwagger2

public class SwaggerConfig {



@Bean

public Docket myApi() {

return new Docket(DocumentationType.SWAGGER_2);

}

}

三、配置spring配置文件，添加swagger配置。具体如下：

<!-- Enables swgger ui -->

<mvc:resources mapping="swagger-ui.html" location="classpath:/META-INF/resources/"/>

<mvc:resources mapping="/webjars/**" location="classpath:/META-INF/resources/webjars/"/>

四、编写测试controller类,如：

1.Controller类

package com.mark.controller;

import com.mangofactory.swagger.annotations.ApiIgnore;
import com.mark.util.RspMsg;
import com.wordnik.swagger.annotations.ApiOperation;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.ResponseBody;
import org.springframework.web.bind.annotation.RestController;
import org.springframework.web.servlet.ModelAndView;

/**
 * 用户相关操作controller
 *
 * @author maliqiang
 * @version 1.0
 * @create 2017-04-27
 */
@RestController
//@RequestMapping("user")
public class UserController {
    @ResponseBody
    @RequestMapping("/login")
    @ApiOperation(value = "用户登录")
    public RspMsg login(){
        RspMsg rsp = new RspMsg();
        return rsp;
    }

    @ApiIgnore//生成接口文档时忽略
    @RequestMapping("/info")
    public ModelAndView swaggerInfo() {
        String url="redirect:swagger/swagger-ui.html";
        return new ModelAndView(url);
    }
}

2.辅助类

package com.mark.util;

/**
 * @author maliqiang
 * @version 1.0
 * @create 2017-04-27
 */
public class RspMsg {
    private Integer code;
    private String msg;
    private Object data;
    private boolean flag;

    public RspMsg(Integer code, String msg, Object data, boolean flag) {
        this.code = code;
        this.msg = msg;
        this.data = data;
        this.flag = flag;
    }

    public RspMsg() {
        this.code = 0000;
        this.msg = "操作成功";
        this.flag = true;
    }

    public Integer getCode() {
        return code;
    }

    public void setCode(Integer code) {
        this.code = code;
    }

    public String getMsg() {
        return msg;
    }

    public void setMsg(String msg) {
        this.msg = msg;
    }

    public Object getData() {
        return data;
    }

    public void setData(Object data) {
        this.data = data;
    }

    public boolean isFlag() {
        return flag;
    }

    public void setFlag(boolean flag) {
        this.flag = flag;
    }
}

然后，启动项目。访问地址：localhost:8080/项目名/swagger-ui.html即可看到项目的api文档。当然，实际使用时应清楚的标注方法适用的范围：post、get、delete等。

访问界面如下：