SpringBoot与Swagger2整合

一、Swagger简介与优势

相信各位在公司写API文档数量应该不少，当然如果你还处在自己一个人开发前后台的年代，当我没说，如今为了前后台更好的对接，还为了以后交接方便，都有要求写API文档。

Swagger是一款Restful接口的文档在线自动生成+功能测试的软件。

Swagger是一个规范和完整的框架。用于生成、描述、调用和可视化Restful风格的Web服务。总体目标是使客户端和文件系统

作为服务器以同样的速度来更新文件的方法、参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。

手写Api文档的几个痛点：

文档需要更新的时候，需要再次发送一份给前端，也就是文档更新交流不及时。
接口返回结果不明确
不能直接在线测试接口，通常需要使用工具，比如postman
接口文档太多，不好管理

Swagger也就是为了解决这个问题，当然也不能说Swagger就一定是完美的，当然也有缺点，最明显的就是代码移入性比较强。

其他的不多说，想要了解Swagger的，可以去Swagger官网，可以直接使用Swagger editor编写接口文档，当然我们这里讲解的是SpringBoot整合Swagger2，直接生成接口文档的方式。

二、SpringBoot Swagger2整合 ,本项目环境springboot版本为 2.1.0,jdk1.8

第一步：jar包的引入：

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

第二步:controller层实现swagger接口类 ExternalVoucherAttachAPI

几个注意点,

1.由于本项目涉及到具体的业务类,initialize和setReqAndRes这两个方法可以不用看

2.用到的几个swagger注解

@ApiOperation  用在请求的方法上，说明方法的用户和作用

@ApiResponses  用在请求的方法上，表示一组响应。可以包含多个@ApiResponse()

@ApiResponse()  用于表示一个响应信息

@RequestBody   swagger的post请求需要的参数是body类型,get请求用到的是 @ApiImplicitParams(),规范的接口文档都是这样要求的

@ApiImplicitParams  用在请求的方法上，表示一组参数说明，可以包含多个@ApiImplicitParam()

@ApiImplicitParam  指定一个请求参数的各个方面

ApiSuccess.class 这是我们自己的单独写的响应类,会在下面展示

实体类用到的注解:

@ApiModel  用在响应类上，表示一个返回响应数据的信息。

@ApiModelProperty 用在属性上，描述响应类的属性


①下面是ExternalVoucherAttachAPI类的代码:

package assp.evoucher.external.http;

import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;

import assp.evoucher.external.http.call.VoucherAttach;
import assp.evoucher.external.http.model.ApiSuccess;
import assp.evoucher.external.http.model.UploadAttach;
import io.swagger.annotations.*;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.ModelAttribute;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;

import springfox.documentation.annotations.ApiIgnore;

import java.io.IOException;

@Controller
public class ExternalVoucherAttachAPI {

    private static Logger logger = LoggerFactory.getLogger(ExternalVoucherAttachAPI.class);
//项目具体的业务 可以不看 开始
    protected HttpContext httpContext;

    @ModelAttribute
    public void setReqAndRes(HttpServletRequest request,
                             HttpServletResponse response) {
        httpContext = new HttpContext();
        httpContext.setRequest(request);
        httpContext.setResponse(response);
        httpContext.setSession(request.getSession());
    }

    /**
     * 初始化
     * @return
     */
    private Object initialize(Class<?> className){
        Object queryCglib = null;
        try {
            HttpCallInterceptor cglib = new HttpCallInterceptor(httpContext);
            queryCglib = cglib.getInstance(className);
        } catch (Exception e) {
            logger.error("对象序列话失败, cause by:" + e.getMessage(), e);
        }
        return queryCglib;
    }

//项目具体的业务 可以不看 结束


    @ApiOperation(value = "上传附件")
    @ApiResponses({@ApiResponse(code = 200, message = "正确返回" ,response =ApiSuccess.class)})
    @RequestMapping(value = "/external/uploadAttach",method = RequestMethod.POST)
    public void uploadAttach(@RequestBody UploadAttach uploadAttach)  {
        VoucherAttach voucherAttach = (VoucherAttach)this.initialize(VoucherAttach.class);
        httpContext.setObiect(uploadAttach);
        voucherAttach.uploadAttachById(httpContext);
    }
    @ApiOperation(value = "根据附件ID获取附件")
    @ApiImplicitParams({
            @ApiImplicitParam(required = true, name = "certID", value = "证书ID", paramType = "query", dataType = "string"),
            @ApiImplicitParam(required = true, name = "attachId", value = "附件ID", paramType = "query", dataType = "string")
    })
    @ApiResponses({@ApiResponse(code = 200, message = "正确返回" ,response = ApiSuccess.class)})
    @RequestMapping(value = "/external/downloadAttachById",method = RequestMethod.GET)
    public void downloadAttachById(){
        VoucherAttach voucherAttach = (VoucherAttach)this.initialize(VoucherAttach.class);
        voucherAttach.downloadAttachById(httpContext);
    }

    @ApiOperation(value = "根据附件ID删除附件")
    @ApiImplicitParams({
            @ApiImplicitParam(required = true, name = "certID", value = "证书ID", paramType = "query", dataType = "string"),
            @ApiImplicitParam(required = true, name = "attachId", value = "附件ID", paramType = "query", dataType = "string")
    })
    @ApiResponses({@ApiResponse(code = 200, message = "正确返回" ,response = ApiSuccess.class)})
    @RequestMapping(value = "/external/deleteAttachById",method = RequestMethod.GET)
    public void deleteAttachById(){
        VoucherAttach voucherAttach = (VoucherAttach)this.initialize(VoucherAttach.class);
        voucherAttach.deleteAttachForID(httpContext);
    }
}

②下面是 post请求参数 实体类UploadAttach的代码: 

CommonParameter类是公共参数,所有的post请求实体类继承该类

package assp.evoucher.external.http.model;

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

@ApiModel(value="UploadAttach")
public class UploadAttach extends CommonParameter {

    @ApiModelProperty(value="机构证书ID",required=true)
    private String certID;

    @ApiModelProperty(value="附件类型",required=true)
    private String attachType;

    @ApiModelProperty(value="附件名称",required=true)
    private String attachName;

    @ApiModelProperty(value="附件分类",required=true)
    private String attachLab;

    @ApiModelProperty(value="data",required=true)
    private String data;

    public String getCertID() {
        return certID;
    }

    public void setCertID(String certID) {
        this.certID = certID;
    }

    public String getData() {
        return data;
    }

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

    public void setAttachType(String attachType) {
        this.attachType = attachType;
    }
    public String getAttachType() {
        return attachType;
    }

    public String getAttachName() {
        return attachName;
    }

    public void setAttachName(String attachName) {
        this.attachName = attachName;
    }
    public String getAttachLab() {
        return attachLab;
    }

    public void setAttachLab(String attachLab) {
        this.attachLab = attachLab;
    }
}

③下面是实体父类CommonParameter 的代码

package assp.evoucher.external.http.model;

import io.swagger.annotations.ApiModelProperty;


public class CommonParameter {

    @ApiModelProperty(value="应用ID",required=true)
    protected String appid;

    @ApiModelProperty(value="预算单位编码",required=true)
    protected String agencycode;

    @ApiModelProperty(value="当前系统时间戳",required=true)
    protected String timestamp;

    @ApiModelProperty(value="随机正整数",required=true)
    protected String random;

    @ApiModelProperty(value="签名结果",required=true)
    protected String signresult;

    public String getAppid() {
        return appid;
    }

    public void setAppid(String appid) {
        this.appid = appid;
    }

    public String getAgencycode() {
        return agencycode;
    }

    public void setAgencycode(String agencycode) {
        this.agencycode = agencycode;
    }

    public String getTimestamp() {
        return timestamp;
    }

    public void setTimestamp(String timestamp) {
        this.timestamp = timestamp;
    }

    public String getRandom() {
        return random;
    }

    public void setRandom(String random) {
        this.random = random;
    }

    public String getSignresult() {
        return signresult;
    }

    public void setSignresult(String signresult) {
        this.signresult = signresult;
    }
}

④ApiSuccess 这是我们自己的单独写的响应类

package assp.evoucher.external.http.model;

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

@ApiModel(value="ApiResponse")
public class ApiSuccess {
    
    @ApiModelProperty(value="返回码 ",example="1成功，失败对应异常编码，格式EVS000 ")
    private int code;
    
    @ApiModelProperty(value="异常原因 ")
    private String reason;
    
    @ApiModelProperty(value="接口调用成功后的数据结果")
    private String data;
    
    public int getCode() {
        return code;
    }
    public void setCode(int code) {
        this.code = code;
    }
    public String getReason() {
        return reason;
    }
    public void setReason(String reason) {
        this.reason = reason;
    }
    public String getData() {
        return data;
    }
    public void setData(String data) {
        this.data = data;
    }

}

第三步：swagger的配置启动类编写：

关于几个注意点:

1.访问404的原因,首先Spring Boot自动配置本身不会自动把/swagger-ui.html这个路径映射到对应的目录META-INF/resources/下面。

所以我们需要动态的进行mvc资源文件的指定,所以会用到 addResourceHandlers 方法

2.本项目get请求和post请求分开,由于会用到一些公共参数

get请求采用了如下配置

也就是上面的该方法 customDocket_get() ,这样我们提供的接口方法需要的参数不用在每个实体类上继成公共类

post请求采用了如下配置

也就是该方法 customDocket_post(),post请求采用的接口需要的参数在每个实体类上继成公共类

3.在请求的方法上，表示一组响应

responseMessageList.add(new ResponseMessageBuilder().code(200)

                .message("正确返回").responseModel(new ModelRef("ApiSuccess"))
                .build());

4.需要swagger展示的接口需要指定包路径.apis(SwaggerApiSelectors.basePackageAndRequestMethod("assp.evoucher.external.http", RequestMethod.GET))

下面是SwaggerConfig的代码:

package assp.evoucher.sysmgr;

import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.PropertySource;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.servlet.config.annotation.EnableWebMvc;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurationSupport;

import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
import springfox.documentation.builders.*;
import springfox.documentation.schema.ModelRef;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.service.Parameter;
import springfox.documentation.service.ResponseMessage;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

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

@Configuration
@EnableSwagger2

public class SwaggerConfig implements WebMvcConfigurer {

   //get请求配置
    @Bean
    public Docket customDocket_get() {
         //指定一组响应,本项目只指定响应200的描述
        List<ResponseMessage> responseMessageList = new ArrayList<ResponseMessage>();
        responseMessageList.add(new ResponseMessageBuilder().code(200)
                .message("正确返回").responseModel(new ModelRef("ApiSuccess"))
                .build());
       //所有的get请求加上公共参数
        ParameterBuilder parameterBuilder = new ParameterBuilder();
        List<Parameter> params = new ArrayList<>();
        parameterBuilder.name("appid").description("应用ID").modelRef(new ModelRef("string"))
                .parameterType("query").required(true);
        params.add(parameterBuilder.build());
        parameterBuilder.name("agencycode").description("预算单位编码").modelRef(new ModelRef("string"))
                .parameterType("query").required(true);
        params.add(parameterBuilder.build());
        parameterBuilder.name("timestamp").description("当前系统时间戳").modelRef(new ModelRef("string"))
                .parameterType("query").required(true);
        params.add(parameterBuilder.build());
        parameterBuilder.name("random").description("随机正整数").modelRef(new ModelRef("string"))
                .parameterType("query").required(true);
        params.add(parameterBuilder.build());
        parameterBuilder.name("signresult").description("签名结果").modelRef(new ModelRef("string"))
                .parameterType("query").required(true);
        params.add(parameterBuilder.build());
        /*
         * responseMessageList.add(new ResponseMessageBuilder().code(404)
         * .message("找不到资源").responseModel(new ModelRef("ApiError")) .build());
         * responseMessageList.add(new ResponseMessageBuilder().code(500)
         * .message("服务器内部错误").responseModel(new ModelRef("ApiError"))
         * .build()); responseMessageList.add(new
         * ResponseMessageBuilder().code(409)
         * .message("业务逻辑异常").responseModel(new ModelRef("ApiError")) .build());
         * responseMessageList.add(new ResponseMessageBuilder().code(422)
         * .message("参数校验异常").responseModel(new ModelRef("ApiError")) .build());
         * responseMessageList.add(new ResponseMessageBuilder().code(503)
         * .message("Hystrix异常").responseModel(new ModelRef("ApiError"))
         * .build());
         */

        return new Docket(DocumentationType.SWAGGER_2).groupName("get")
                .globalResponseMessage(RequestMethod.GET, responseMessageList)
                .globalResponseMessage(RequestMethod.POST, responseMessageList)
                .globalResponseMessage(RequestMethod.PUT, responseMessageList)
                .globalResponseMessage(RequestMethod.DELETE,
                        responseMessageList).apiInfo(apiInfo()).select()
                    .apis(SwaggerApiSelectors.basePackageAndRequestMethod("assp.evoucher.external.http", RequestMethod.GET))
                .paths(PathSelectors.any())
                .build().globalOperationParameters(params);
                //.pathMapping("/external");
                //.host(host); // 在这里可以设置请求的统一前缀

    }
//post请求配置
    @Bean
    public Docket customDocket_post() {
        List<ResponseMessage> responseMessageList = new ArrayList<ResponseMessage>();
        responseMessageList.add(new ResponseMessageBuilder().code(200)
                .message("正确返回").responseModel(new ModelRef("ApiSuccess"))
                .build());
        /*
         * responseMessageList.add(new ResponseMessageBuilder().code(404)
         * .message("找不到资源").responseModel(new ModelRef("ApiError")) .build());
         * responseMessageList.add(new ResponseMessageBuilder().code(500)
         * .message("服务器内部错误").responseModel(new ModelRef("ApiError"))
         * .build()); responseMessageList.add(new
         * ResponseMessageBuilder().code(409)
         * .message("业务逻辑异常").responseModel(new ModelRef("ApiError")) .build());
         * responseMessageList.add(new ResponseMessageBuilder().code(422)
         * .message("参数校验异常").responseModel(new ModelRef("ApiError")) .build());
         * responseMessageList.add(new ResponseMessageBuilder().code(503)
         * .message("Hystrix异常").responseModel(new ModelRef("ApiError"))
         * .build());
         */

        return new Docket(DocumentationType.SWAGGER_2).groupName("post")
                .globalResponseMessage(RequestMethod.GET, responseMessageList)
                .globalResponseMessage(RequestMethod.POST, responseMessageList)
                .globalResponseMessage(RequestMethod.PUT, responseMessageList)
                .globalResponseMessage(RequestMethod.DELETE,
                        responseMessageList).apiInfo(apiInfo()).select()
                .apis(SwaggerApiSelectors.basePackageAndRequestMethod("assp.evoucher.external.http", RequestMethod.POST))//指定需要用swagger展示的包路径
                .paths(PathSelectors.any())
                .build();
        //.pathMapping("/external");
        //.host(host); // 在这里可以设置请求的统一前缀

    }
  //swagger文档描述
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                //页面标题
                .title("服务端接口")
                //创建人
                .contact(new Contact("ctjsoft", "http://www.ctjsoft.com/", ""))
                //版本号
                .version("1.0")
                //描述
                .description("API 描述")
                .build();
    }
  //动态的进行mvc资源文件的指定,所以会用到 addResourceHandlers 方法,否则可能会出现404问题
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
    /*    registry.addResourceHandler("/**").addResourceLocations(
                "classpath:/static/");*/
        registry.addResourceHandler("swagger-ui.html").addResourceLocations(
                "classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**").addResourceLocations(
                "classpath:/META-INF/resources/webjars/");

    }
}

第四步：如果需要展示swagger接口的controller类跟项目启动类不在同一个包下,需要在启动类中用ComponentScan指定扫描路径

package assp.evoucher.sysmgr;

import org.apache.axis.transport.http.AxisServlet;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.boot.autoconfigure.jdbc.DataSourceAutoConfiguration;
import org.springframework.boot.builder.SpringApplicationBuilder;
import org.springframework.boot.web.servlet.ServletRegistrationBean;
import org.springframework.boot.web.servlet.support.SpringBootServletInitializer;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.ComponentScan;

@SpringBootApplication
@ComponentScan(basePackages = {"assp.*"})//指定swagger接口所在路径
public class EvoucherApplication {

    public static void main(String[] args) {
        SpringApplication.run(EvoucherApplication.class, args);
    }
}

}

第五步:访问swagger路径 http://localhost:8083/realware/swagger-ui.html,SpringBoot Swagger2整合完毕

get请求与post请求分离(本项目get请求与post请求分开单独做一些业务处理,也可以不分开):

get请求:

具体参数:

post请求:

具体参数:

点击 Try it out! 开始测试接口

posted @ 2019-04-17 17:23 小柳爱吃肉阅读(778) 评论(0) 编辑收藏举报

会员力量，点亮园子希望

刷新页面返回顶部

stay lucky

万事皆因忙中错，好人半自苦中来

SpringBoot与Swagger2整合

公告