Swagger UI 与SpringMVC的整合

关于 Swagger

Swagger能成为最受欢迎的REST APIs文档生成工具之一，有以下几个原因：

• Swagger 可以生成一个具有互动性的API控制台，开发者可以用来快速学习和尝试API。
• Swagger 可以生成客户端SDK代码用于各种不同的平台上的实现。
• Swagger 文件可以在许多不同的平台上从代码注释中自动生成。
• Swagger 有一个强大的社区，里面有许多强悍的贡献者。

Swagger 文档提供了一个方法，使我们可以用指定的 JSON 或者 YAML 摘要来描述你的 API，包括了比如 names、order 等 API 信息。

你可以通过一个文本编辑器来编辑 Swagger 文件，或者你也可以从你的代码注释中自动生成。各种工具都可以使用 Swagger 文件来生成互动的 API 文档。

Swagger 、SwaggerUI与SpringMVC的整合

1.Maven引入

<dependency>
    <groupId>javax.servlet</groupId>
    <artifactId>javax.servlet-api</artifactId>
    <version>3.1.0</version>
    <scope>provided</scope>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.5.0</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.5.0</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-staticdocs</artifactId>
    <version>2.5.0</version>
</dependency>
<dependency>
    <groupId>org.hibernate</groupId>
    <artifactId>hibernate-validator</artifactId>
    <version>5.2.4.Final</version>
</dependency>

2.配置webconfig.xml

将 DispatcherServlet 的 url-pattern 改为 /

<servlet>
    <servlet-name>springMvc</servlet-name>
    <servlet-class>org.springframework.web.servlet.DispatcherServlet</servlet-class>
    <init-param>
      <param-name>contextConfigLocation</param-name>
      <param-value>classpath:spring-mvc.xml</param-value>
    </init-param>
    <load-on-startup>1</load-on-startup>
  </servlet>
  <servlet-mapping>
    <servlet-name>springMvc</servlet-name>
    <url-pattern>/</url-pattern>
  </servlet-mapping>

3.在spring-mvc.xml中添加自动扫描

<mvc:annotation-driven  />

    <!-- 自动扫描(自动注入) -->
     <context:component-scan base-package="com.xhl.swagger.api"/>
     <mvc:default-servlet-handler/>

4.新建Swagger配置类

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurerAdapter;

import com.google.common.base.Predicates;

import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class SwaggerConfig extends WebMvcConfigurerAdapter {

     @Bean
        public Docket api() {
            return new Docket(DocumentationType.SWAGGER_2).select()
                    .apis(Predicates.not(RequestHandlerSelectors.basePackage("org.springframework.boot")))
                    .build();
        }

        @Override
        public void addResourceHandlers(ResourceHandlerRegistry registry)
        {
            registry.addResourceHandler("swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");
            registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
        }
}

5.建测试的Controller和常量

public interface Constants {
    /****** 系统标识符 开始 *********/
    /**
    * 错误 描述
    */
    String MSG_ERROR = "error";
    /**
    * 成功 描述
    */
    String MSG_SUCCESS = "OK";

    /****** 系统状态码 开始 ******/
    /**
    * 请求失败
    */
    int ERROR = 100;
    /**
    * 请求成功
    */
    int SUCCESS = 200;
}

import java.io.Serializable;

import com.fasterxml.jackson.annotation.JsonInclude;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;

@ApiModel
@JsonInclude(JsonInclude.Include.NON_NULL)
public class Result<T> implements Serializable {

    private static final long serialVersionUID = 1L;

    /** 正常状态为0或200 **/
    @ApiModelProperty(value = "状态代码", name = "状态代码")
    private int code;

    /** 是code异常时，返回的错误信息（app直接显示） **/
    @ApiModelProperty(value = "错误码描述", name = "错误码描述")
    private String message;

    /** 返回的数据对象 **/
    @ApiModelProperty(value = "数据对象", name = "数据对象")
    private T data;

    /** 是code正常时的提示（不为空，app直接展示） **/
    @ApiModelProperty(value = "code正常时的提示信息", name = "code正常时的提示信息")
    private String toast = "";

    /** response中允许 空值，不允许 NULL值出现 **/
    @ApiModelProperty(value = "响应流信息", name = "响应流信息")
    private String response = "";

    public Result() {
    }

    public Result(int code,String message) {
        this.code = code;
        this.message = message;
    }

    public Result(int code,String message,T data) {
        this.code = code;
        this.message = message;
        this.data = data;
    }

    public Result(int code,String message,T data,String toast,String response) {
        this.code = code;
        this.message = message;
        this.data = data;
        this.toast = toast;
        this.response = response;
    }

    public int getCode() {
        return code;
    }

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

    public String getMessage() {
        return message;
    }

    public void setMessage(String message) {
        this.message = message;
    }

    public T getData() {
        return data;
    }

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

    public String getToast() {
        return toast;
    }

    public void setToast(String toast) {
        this.toast = toast;
    }

    public String getResponse() {
        return response;
    }

    public void setResponse(String response) {
        this.response = response;
    }
   @Override
    public String toString() {
        return "Result{" +
                "code=" + code +
                ", message='" + message + '\'' +
                ", data=" + data + '\'' +
                ", toast=" + toast + '\'' +
                ", response=" + response +
                '}';
    }
}

@ApiModel(value = "用户信息")
public class UserVo {
    @ApiModelProperty(value = "用户id", required = true)
    private String userId;
    @ApiModelProperty(value = "昵称", required = true)
    private String userName;
    public String getUserId() {
        return userId;
    }
    public void setUserId(String userId) {
        this.userId = userId;
    }
    public String getUserName() {
        return userName;
    }
    public void setUserName(String userName) {
        this.userName = userName;
    }
}

import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

import com.qdingnet.pcloud.api.common.utils.StringUtils;
import com.qdingnet.pcloud.api.swagger.constants.Constants;
import com.qdingnet.pcloud.api.swagger.constants.Result;
import com.qdingnet.pcloud.api.swagger.vo.UserVo;

import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;

@RestController
@RequestMapping("/api/json/user")
public class SwaggerController {

    @RequestMapping(value = "/add", method = RequestMethod.POST)
    @ApiOperation(value = "添加用户", notes = "增加用户")
    public Result<UserVo> add(@ApiParam(name = "token", value = "token",required = true) @RequestParam(name = "token", required = true) String token,
                              @ApiParam(name = "userName",value = "用户昵称",required = true)@RequestParam(name = "userName",required = true)String userName,
                              @ApiParam(name = "mobile",value = "手机",required = true)@RequestParam(name = "mobile",required = true)String mobile,
                              @ApiParam(required = true, name = "email", value = "邮箱") @RequestParam(name = "email", required = true) String email ) {
        UserVo userVo = new UserVo();
        userVo.setUserId(StringUtils.getUUID());
        userVo.setUserName(userName);
        return new Result<UserVo>(Constants.SUCCESS,Constants.MSG_SUCCESS,userVo);
    }

    @RequestMapping(value = "/getUser", method = RequestMethod.GET)
    @ApiOperation(value = "测试获取用户", notes = "测试获取用户")
    public Result<UserVo> getUser() {
        UserVo userVo = new UserVo();
        userVo.setUserId(StringUtils.getUUID());
        userVo.setUserName("测试获取用户");
        return new Result<UserVo>(Constants.SUCCESS,Constants.MSG_SUCCESS,userVo);
    }
}

6.测试运行

首先通过：http://localhost:8080/工程名/api/json/user/getUser.do  可以访问：

{"code":200,"message":"OK","data":{"userId":"d1239dc4e4164662af754c64e42762cd","userName":"测试获取用户"},"toast":"","response":""}

其次通过：http://localhost:8080/工程名/v2/api-docs 可以查看具体的接口描述信息：

最后通过：http://localhost:8080/工程名/swagger-ui.html 进行访问和测试：

7.如果请求需要带参数的话，Swagger可以直接显示出可以输入请求参数的入口和描述：

请求结果：

Try it out