java webApi统一格式使用swagger框架

1、pom.xml添加配置

        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.9.2</version>
        </dependency>

2、App.java插入注解

@SpringBootApplication
@EnableSwagger2
public class App 
{
    public static void main( String[] args )
    {
        SpringApplication.run(App.class,args);
    }
}

3、控制器类

package test.testApi.Controller;

import java.util.ArrayList;
import java.util.List;

import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RestController;

import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import test.testApi.Model.ResponseData;
import test.testApi.Model.ResponseResult;
import test.testApi.Model.Student;


@RestController
public class TestController {
    @ApiOperation(value = "查询数据")
    @RequestMapping(value= "/TestGet/{id}",method=RequestMethod.GET)
    public ResponseResult<List<Student>> TestGet(@ApiParam(name = "id", value = "主键ID", required = true) @PathVariable String id) {
        List<Student> stuList=new ArrayList<Student>();
        
        Student stu = new Student();
        stu.name="李四";
        stu.age=12;
        stu.sex=true;
        stuList.add(stu);
        Student stu2 = new Student();
        stu2.name="王五";
        stu2.age=13;
        stu2.sex=false;
        stuList.add(stu2);
        return ResponseData.makeOKRsp(stuList);
    }
    
    @ApiOperation(value = "新增数据")
    @RequestMapping(value= "",method=RequestMethod.POST)
    public ResponseResult<?> TestPost(@RequestBody @ApiParam(name="用户对象",value="传入json格式",required=true) Student stu) {        
        return ResponseData.makeOKRsp("新增成功!");
    }
    
    @ApiOperation(value = "修改数据")
    @RequestMapping(value= "TestPut",method=RequestMethod.PUT)
    public ResponseResult<?> TestPut(@RequestBody @ApiParam(name="用户对象",value="传入json格式",required=true) Student stu) {
        return ResponseData.makeOKRsp("修改成功!");
    }
    
    @ApiOperation(value = "删除数据")
    @RequestMapping(value= "/TestDel/{id}",method=RequestMethod.DELETE)
    public ResponseResult<?> TestDel(@ApiParam(name = "id", value = "主键ID", required = true) @PathVariable String id){
        return ResponseData.makeOKRsp("删除成功!");
    }
}

4、swagger配置类

package test.testApi.Controller;

import com.google.common.base.Predicates;
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.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket webApiConfig() {
        return new Docket(DocumentationType.SWAGGER_2).groupName("webApi").apiInfo(webApiInfo()).select()
                .paths(Predicates.not(PathSelectors.regex("/admin/.*")))
                .paths(Predicates.not(PathSelectors.regex("/error.*"))).build();

    }

    private ApiInfo webApiInfo() {

        return new ApiInfoBuilder().title("测试API文档").description("本文档描述了接口定义").version("1.0")
                .contact(new Contact("java", "http://123.com", "1123@qq.com")).build();
    }
}

5、CorsConfig跨域配置类

package test.testApi.Controller;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.cors.CorsConfiguration;
import org.springframework.web.cors.UrlBasedCorsConfigurationSource;
import org.springframework.web.filter.CorsFilter;

@Configuration
public class CorsConfig {
    private CorsConfiguration buildConfig() {
        CorsConfiguration corsConfiguration = new CorsConfiguration();
        corsConfiguration.addAllowedOrigin("*"); // 允许任何域名使用
        corsConfiguration.addAllowedHeader("*"); // 允许任何头
        corsConfiguration.addAllowedMethod("*"); // 允许任何方法（post、get等）
        return corsConfiguration;
    }

    @Bean
    public CorsFilter corsFilter() {
        UrlBasedCorsConfigurationSource source = new UrlBasedCorsConfigurationSource();
        source.registerCorsConfiguration("/**", buildConfig());
        return new CorsFilter(source);
    }
}

6、封装输出实体类方法

package test.testApi.Model;

public class ResponseData {
    private final static String SUCCESS = "success";
 
    public static <T> ResponseResult<T> makeOKRsp() {
        return new ResponseResult<T>().setCode(ResultCode.SUCCESS).setMsg(SUCCESS);
    }
 
    public static <T> ResponseResult<T> makeOKRsp(String message) {
        return new ResponseResult<T>().setCode(ResultCode.SUCCESS).setMsg(message);
    }
 
    public static <T> ResponseResult<T> makeOKRsp(T data) {
        return new ResponseResult<T>().setCode(ResultCode.SUCCESS).setMsg(SUCCESS).setData(data);
    }
 
    public static <T> ResponseResult<T> makeErrRsp(String message) {
        return new ResponseResult<T>().setCode(ResultCode.INTERNAL_SERVER_ERROR).setMsg(message);
    }
 
    public static <T> ResponseResult<T> makeRsp(int code, String msg) {
        return new ResponseResult<T>().setCode(code).setMsg(msg);
    }
 
    public static <T> ResponseResult<T> makeRsp(int code, String msg, T data) {
        return new ResponseResult<T>().setCode(code).setMsg(msg).setData(data);
    }
}

7、封装输出实体类

package test.testApi.Model;

public class ResponseResult<T> {
     
    public int code; //返回状态码200成功
 
    private String msg; //返回描述信息
 
    private T data; //返回内容体
 
    public ResponseResult<T> setCode(ResultCode retCode) {
        this.code = retCode.code;
        return this;
    }
 
    public int getCode() {
        return code;
    }
 
    public ResponseResult<T> setCode(int code) {
        this.code = code;
        return this;
    }
 
    public String getMsg() {
        return msg;
    }
 
    public ResponseResult<T> setMsg(String msg) {
        this.msg = msg;
        return this;
    }
 
    public T getData() {
        return data;
    }
 
    public ResponseResult<T> setData(T data) {
        this.data = data;
        return this;
    }
 
}

8、输出状态编码枚举

package test.testApi.Model;

public enum ResultCode {
    // 成功
    SUCCESS(200),

    // 失败
    FAIL(400),

    // 未认证（签名错误）
    UNAUTHORIZED(401),

    // 接口不存在
    NOT_FOUND(404),

    // 服务器内部错误
    INTERNAL_SERVER_ERROR(500);

    public int code;

    ResultCode(int code) {
        this.code = code;
    }
}

9、学生实体类

package test.testApi.Model;

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

@ApiModel(description="学生类")
public class Student {
    @ApiModelProperty(value ="姓名",example="张三")
    public String name; 
    @ApiModelProperty(value ="年龄",example="12")
    public int age;
    @ApiModelProperty(value ="性别:男true,女false",example="0")
    public boolean sex;
}

10、运行测试

运行后调用：http://localhost:8080/swagger-ui.html