【swagger】2.swagger提供开发者文档--返回统一格式篇【spring mvc】【spring boot】

接着上一篇来说，

不管正常返回结果还是后台出现异常，应该返回给前台统一的响应格式。

所以这一篇就为了应对解决这个问题。

========================================================================

1.首先，定义一个统一返回类【所有返回的格式都是这个类的格式】

package com.sxd.sweeping.response;

import com.alibaba.fastjson.JSON;
import lombok.*;

import java.io.Serializable;
import java.util.Objects;

/**
 * 统一JSON返回类
 * @author sxd
 * @since 2018/4/1
 */
@Getter
@Setter
@NoArgsConstructor
@AllArgsConstructor
public class GenericResponse implements Serializable{

    /**
     * 程序定义状态码
     */
    private int code;
    /**
     * 必要的提示信息
     */
    private String message;
    /**
     * 业务数据
     */
    private Object datas;

    /**
     * 对业务数据单独处理
     * @return
     */
    @Override
    public String toString() {
        if(Objects.isNull(this.datas)){
            this.setDatas(new Object());
        }
        return JSON.toJSONString(this);
    }
}

2.定义统一返回数据格式【这里定义了一些常用返回code+msg，用于填充上面的统一格式】

package com.sxd.sweeping.response;

import com.google.common.collect.Maps;

import java.util.Map;

/**
 * 统一返回客户端数据格式
 * @author sxd
 * @since 2018/4/1
 */
public class ResponseFormat {

    private static Map<Integer,String> messageMap = Maps.newHashMap();
    //初始化状态码与文字说明
    static {
        /* 成功状态码 */
        messageMap.put(200, "成功");

        /* 服务器错误 */
        messageMap.put(1000,"服务器错误");

        /* 参数错误：10001-19999 */
        messageMap.put(10001, "参数无效");
        messageMap.put(10002, "参数为空");
        messageMap.put(10003, "参数类型错误");
        messageMap.put(10004, "参数缺失");

        /* 用户错误：20001-29999*/
        messageMap.put(20001, "用户未登录");
        messageMap.put(20002, "账号不存在或密码错误");
        messageMap.put(20003, "账号已被禁用");
        messageMap.put(20004, "用户不存在");
        messageMap.put(20005, "用户已存在");

        /* 业务错误：30001-39999 */
        messageMap.put(30001, "某业务出现问题");

        /* 系统错误：40001-49999 */
        messageMap.put(40001, "系统繁忙，请稍后重试");

        /* 数据错误：50001-599999 */
        messageMap.put(50001, "数据未找到");
        messageMap.put(50002, "数据有误");
        messageMap.put(50003, "数据已存在");
        messageMap.put(50004,"查询出错");

        /* 接口错误：60001-69999 */
        messageMap.put(60001, "内部系统接口调用异常");
        messageMap.put(60002, "外部系统接口调用异常");
        messageMap.put(60003, "该接口禁止访问");
        messageMap.put(60004, "接口地址无效");
        messageMap.put(60005, "接口请求超时");
        messageMap.put(60006, "接口负载过高");

        /* 权限错误：70001-79999 */
        messageMap.put(70001, "无权限访问");
    }
    public static GenericResponse retParam(Integer status,Object data) {
        GenericResponse json = new GenericResponse(status, messageMap.get(status), data);
        return json;
    }
}

3.定义自己的异常类 因为spring 对于 RuntimeException 异常才会进行事务回滚，所以继承的是RuntimeException【可用于代码中自己throw异常】

package com.sxd.sweeping.handler;

import lombok.Getter;
import lombok.Setter;

/**
 * spring 对于 RuntimeException 异常才会进行事务回滚。
 * @author sxd
 * @since 2018/4/1
 */
@Getter
@Setter
public class MyException extends RuntimeException {

    public MyException(Integer code, Exception exception) {
        this.code = code;
        this.exception = exception;
    }

    private Integer code;
    private Exception exception;
}

4.定义Controller增强器，使用注解@ControllerAdvice，具体使用说明查看代码【对异常进行统一拦截，然后配置返回格式】

package com.sxd.sweeping.handler;

import com.sxd.sweeping.response.GenericResponse;
import com.sxd.sweeping.response.ResponseFormat;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.ui.Model;
import org.springframework.web.bind.WebDataBinder;
import org.springframework.web.bind.annotation.*;

/**
 * controller 增强器 原理是使用AOP对Controller控制器进行增强（前置增强、后置增强、环绕增强）
 * 启动应用后，被 @ExceptionHandler、@InitBinder、@ModelAttribute 注解的方法，都会作用在 被 @RequestMapping 注解的方法上。
 * @ModelAttribute：在Model上设置的值，对于所有被 @RequestMapping 注解的方法中，都可以通过 ModelMap获取，或者通过@ModelAttribute("author")也可以获取
 * @ExceptionHandler 拦截了异常，我们可以通过该注解实现自定义异常处理。其中，@ExceptionHandler 配置的 value 指定需要拦截的异常类型，下面拦截了 Exception.class 这种异常。
 * @author sxd
 * @since 2018/4/1
 */
@ControllerAdvice
public class MyControllerAdvice {

    Logger logger = LoggerFactory.getLogger(this.getClass());
    /**
     * 应用到所有@RequestMapping注解方法，在其执行之前初始化数据绑定器
     * @param binder
     */
    @InitBinder
    public void initBinder(WebDataBinder binder) {}

    /**
     * 把值绑定到Model中，使全局@RequestMapping可以获取到该值
     * @param model
     */
    @ModelAttribute
    public void addAttributes(Model model) {
        model.addAttribute("author", "sxd");
    }

    /**
     * 全局异常捕捉处理
     * @param ex
     * @return
     */
    @ResponseBody
    @ExceptionHandler(value = Exception.class)
    public GenericResponse errorHandler(Exception ex) {
        ex.printStackTrace();
        return ResponseFormat.retParam(1000,null);
    }

    /**
     * 拦截捕捉自定义异常 MyException.class
     * @param ex
     * @return
     */
    @ResponseBody
    @ExceptionHandler(value = MyException.class)
    public GenericResponse myErrorHandler(MyException ex) {
        ex.getException().printStackTrace();
        logger.error(ex.getException().toString());
        return  ResponseFormat.retParam(ex.getCode(),null);
    }
}

5.Swagger类

package com.sxd.sweeping;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class Swagger2 {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.sxd.sweeping.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Spring Boot中使用Swagger2构建RESTful APIs")
                .description("更多精彩博客请关注：http://www.cnblogs.com/sxdcgaq8080/")
                .termsOfServiceUrl("http://www.cnblogs.com/sxdcgaq8080/")
                .contact("Angel挤一挤")
                .version("1.0")
                .build();
    }
}

6.

　　6.1 Controller类

package com.sxd.sweeping.controller;

import com.sxd.sweeping.entity.User;
import com.sxd.sweeping.handler.MyException;
import com.sxd.sweeping.repository.UserRepository;
import com.sxd.sweeping.response.GenericResponse;
import com.sxd.sweeping.response.ResponseFormat;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.data.domain.Page;
import org.springframework.data.domain.PageRequest;
import org.springframework.data.domain.Pageable;
import org.springframework.web.bind.annotation.*;

import java.sql.Date;
import java.util.UUID;

@Api(value = "userController",description = "用户相关操作",tags = {"用户"})
@RestController
@RequestMapping("users")
public class UserController {

    @Autowired
    private UserRepository userRepository;

    @ApiOperation(value = "获取用户详细信息", notes = "根据url的id来获取用户的详细信息")
    @ApiImplicitParam(name = "id", value = "用户ID", required = true,dataType = "Long",paramType = "path")
//    @RequestMapping(value = "/{id}",method = RequestMethod.GET)
    @GetMapping(value = "/{id}")
    public GenericResponse get(@PathVariable Long id){
        User user;
        try{
            user = userRepository.findUserById(id);
        }catch(Exception e){
            user = null;
            throw new MyException(50004,e);
        }
        return ResponseFormat.retParam(200,user);
    }

    @ApiOperation(value = "增加用户", notes = "根据user对象创建用户")
    @ApiImplicitParam(name = "user", value = "用户详细信息User", required = true,dataType = "User")
//    @RequestMapping(method = RequestMethod.POST)
    @PostMapping()
    public GenericResponse add(@RequestBody User user){
        String password = UUID.randomUUID().toString();
        user.setPassword(password);
        user =  userRepository.save(user);

        return ResponseFormat.retParam(200,user);
    }

    @ApiOperation(value = "删除用户", notes = "根据url的id来删除用户")
    @ApiImplicitParam(name = "id", value = "用户ID", required = true,dataType = "Long",paramType = "path")
//    @RequestMapping(value = "/{id}",method = RequestMethod.DELETE)
    @DeleteMapping(value = "/{id}")
    @ResponseBody
    public GenericResponse delete(@PathVariable Long id){
        userRepository.deleteById(id);
        return ResponseFormat.retParam(200,"ID为"+id+"的用户删除成功");
    }

    @ApiOperation(value = "更新用户", notes = "根据url的id来更新用户信息")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long", paramType = "path"),
            @ApiImplicitParam(name = "user", value = "用户实体user", required = true,dataType = "User")
    })
//    @RequestMapping(value = "/{id}",method = RequestMethod.PUT)
    @PutMapping(value = "/{id}")
    public GenericResponse update(@PathVariable Long id, @RequestBody  User user){
        User user1 = userRepository.findUserById(id);
        user1.setGender(user.getGender());
        user1.setMobile(user.getMobile());
        user1.setRealname(user.getRealname());
        user1.setUpdateAt(new Date(System.currentTimeMillis()));

        return  ResponseFormat.retParam(200,user1);
    }

    @ApiOperation(value = "更新用户局部信息", notes = "根据url的id来更新用户局部信息")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long", paramType = "path"),
            @ApiImplicitParam(name = "realname", value = "用户名", required = true,dataType = "String"),
            @ApiImplicitParam(name = "mobile", value = "联系方式", required = true,dataType = "String")
    })
//    @RequestMapping(value = "/{id}",method = RequestMethod.PATCH)
    @PatchMapping(value = "/{id}")
    public GenericResponse patch(@PathVariable Long id, String realname, String mobile){
        User user = userRepository.findUserById(id);
        user.setRealname(realname);
        user.setMobile(mobile);

        return ResponseFormat.retParam(200,userRepository.saveAndFlush(user));
    }

    @ApiOperation(value = "获取用户信息列表", notes = "获取用户信息列表")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "page", value = "页码", required = true,dataType = "int"),
            @ApiImplicitParam(name = "size", value = "单页条数", required = true,dataType = "int")
    })
    @GetMapping()
    public GenericResponse list(
            @RequestParam(name = "page",defaultValue = "1") int page,
            @RequestParam(name = "size",defaultValue = "10") int size){
        Pageable pageable = new PageRequest(page-1,size);
        Page<User> pageList = userRepository.findAll(pageable);
        return  ResponseFormat.retParam(200,pageList);
    }

    @ApiOperation(value = "筛选获取用户信息列表", notes = "筛选获取用户信息列表")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "key", value = "关键字", required = true,dataType = "String"),
            @ApiImplicitParam(name = "startDate", value = "开始时间", required = true,dataType = "Date"),
            @ApiImplicitParam(name = "endDate", value = "结束时间", required = true,dataType = "Date"),
            @ApiImplicitParam(name = "page", value = "页码", required = true,dataType = "int"),
            @ApiImplicitParam(name = "size", value = "单页条数", required = true,dataType = "int")
    })
    @GetMapping(value = "/pageList")
    public GenericResponse pageList(
            @RequestParam(name = "key") String key,
            @RequestParam(name = "startDate") Date startDate,
            @RequestParam(name = "endDate") Date endDate,
            @RequestParam(name = "page",defaultValue = "1") int page,
            @RequestParam(name = "size",defaultValue = "10") int size){
        Pageable pageable = new PageRequest(page-1,size);
        Page<User> pageList = userRepository.pageList(key,startDate,endDate,pageable);
        return  ResponseFormat.retParam(200,pageList);
    }

}

　　6.2 Repository接口

package com.sxd.sweeping.repository;

import com.sxd.sweeping.entity.User;
import org.springframework.data.domain.Page;
import org.springframework.data.domain.Pageable;
import org.springframework.data.jpa.repository.JpaRepository;
import org.springframework.data.jpa.repository.Query;
import org.springframework.data.repository.query.Param;

import java.sql.Date;

public interface UserRepository extends JpaRepository<User,Long> {

    User findUserById(Long id);

    @Query(value = "select u from User u " +
            "where :keyword is null or u.realname like %:keyword% " +
            "and (u.updateAt between :startDate and :endDate)")
    Page<User> pageList(
            @Param("keyword") String keyword,
            @Param("startDate") Date startDate,
            @Param("endDate") Date endDate,
            Pageable pageable);
}

7.对于异常处理，异常日志的记录，所以还需要配置logback日志配置

<?xml version="1.0" encoding="UTF-8"?>

<configuration scan="true" scanPeriod="60 seconds" debug="false">

    <contextName>logback</contextName>
    <!--定义日志文件的存储地址 勿在 LogBack 的配置中使用相对路径-->
    <property name="log.path" value="/Users/sxd/IdeaProjects/A/sweeping.log" />

    <!--输出到控制台-->
    <appender name="console" class="ch.qos.logback.core.ConsoleAppender">
        <filter class="ch.qos.logback.classic.filter.ThresholdFilter">
            <level>INFO</level>
        </filter>
        <encoder>
            <!--<pattern>%d %p (%file:%line\)- %m%n</pattern>-->
            <!--格式化输出：%d:表示日期    %thread:表示线程名     %-5level:级别从左显示5个字符宽度  %msg:日志消息    %n:是换行符-->
            <pattern>%black(控制台-) %red(%d{yyyy-MM-dd HH:mm:ss}) %green([%thread]) %highlight(%-5level) %boldMagenta(%logger) - %cyan(%msg%n)</pattern>
            <charset>UTF-8</charset>
        </encoder>
    </appender>

    <!--输出到文件-->
    <appender name="file" class="ch.qos.logback.core.rolling.RollingFileAppender">
        <file>${log.path}</file>
        <rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy">
            <fileNamePattern>logback.%d{yyyy-MM-dd}.log</fileNamePattern>
            <maxHistory>30</maxHistory>
            <totalSizeCap>1GB</totalSizeCap>
        </rollingPolicy>
        <encoder>
            <!--格式化输出：%d:表示日期    %thread:表示线程名     %-5level:级别从左显示5个字符宽度  %msg:日志消息    %n:是换行符-->
            <pattern>文件记录-%d{yyyy-MM-dd HH:mm:ss} [%thread] %-5level %logger{36} - %msg%n</pattern>
            <charset>UTF-8</charset>
        </encoder>
    </appender>

    <root level="info">
        <appender-ref ref="console" />
        <appender-ref ref="file" />
    </root>

</configuration>

8.application.properties文件

spring.datasource.url = jdbc:postgresql://127.0.0.1:54320/ctgs
spring.datasource.username = homestead
spring.datasource.password = secret
spring.datasource.driver-class-name = org.postgresql.Driver

spring.jpa.database=postgresql
spring.jpa.show-sql=true

debug=true

9.build.gradle依赖

buildscript {
    ext {
        springBootVersion = '2.0.0.RELEASE'
    }
    repositories {
        mavenCentral()
    }
    dependencies {
        classpath("org.springframework.boot:spring-boot-gradle-plugin:${springBootVersion}")
    }
}

apply plugin: 'java'
apply plugin: 'eclipse'
apply plugin: 'org.springframework.boot'
apply plugin: 'io.spring.dependency-management'

group = 'com.sxd'
version = '0.0.1-SNAPSHOT'
sourceCompatibility = 1.8

repositories {
    maven { url 'http://maven.aliyun.com/nexus/content/groups/public/' }
    maven { url "https://repo.spring.io/snapshot" }
    maven { url "https://repo.spring.io/milestone" }
    maven { url 'https://repo.spring.io/plugins-release' }
    maven { url 'https://jitpack.io' }
    mavenCentral()
}

dependencies {
    compile('org.springframework.boot:spring-boot-starter-activemq')
    compile('org.springframework.boot:spring-boot-starter-amqp')
    compile('org.springframework.boot:spring-boot-starter-aop')
    compile('org.springframework.boot:spring-boot-starter-cache')
    compile('org.springframework.boot:spring-boot-starter-data-jpa')
    compile('org.springframework.boot:spring-boot-starter-data-mongodb')
    compile('org.springframework.boot:spring-boot-starter-data-redis')
    compile('org.springframework.boot:spring-boot-starter-data-solr')
    compile('org.springframework.boot:spring-boot-starter-freemarker')
    compile('org.springframework.boot:spring-boot-starter-jdbc')
    compile('org.springframework.boot:spring-boot-starter-validation')
    compile('org.springframework.boot:spring-boot-starter-web')
    compile('org.mybatis.spring.boot:mybatis-spring-boot-starter:1.3.2')
    runtime('com.microsoft.sqlserver:mssql-jdbc')
    runtime('mysql:mysql-connector-java')
    runtime('org.postgresql:postgresql')
    compileOnly('org.projectlombok:lombok')
    testCompile('org.springframework.boot:spring-boot-starter-test')

    // https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui
    compile group: 'io.springfox', name: 'springfox-swagger-ui', version: '2.8.0'
    // https://mvnrepository.com/artifact/io.springfox/springfox-swagger2
    compile group: 'io.springfox', name: 'springfox-swagger2', version: '2.8.0'
    // https://mvnrepository.com/artifact/com.alibaba/fastjson
    compile group: 'com.alibaba', name: 'fastjson', version: '1.2.47'

}

最后 启动项目，访问地址：http://localhost:8080/swagger-ui.html#/

请求操作

正常情况下请求：

错误情况下：

查看日志文件：