springboot 整合 swagger2.x，并导入到YApi

一、swagger配置

1.maven导入依赖

个人用的springboot版本为 2.5.0-M2

<!--swagger2 依赖-->
<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.自定义swagger配置文件

目录结构如下：

自定义swagger配置信息，可以扫描多个包下的接口

package com.example.demo.config.swager;

import com.google.common.base.Function;
import com.google.common.base.Optional;
import com.google.common.base.Predicate;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.RequestHandler;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.service.Parameter;
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;


@EnableSwagger2
@Configuration
public class SwaggerConfig {

    private final boolean enable = true;

    /**
     * 定义分隔符
     */
    private static final String splitor = ";";

    /**
     * 哪些包下的API需要生成swagger文档
     */
    String basePackages = "com.example.demo.controller" + splitor
            + "com.example.demo.controller1"
            ;

    @Bean
    public Docket createRestApi() {
        /**
         * 这是为了我们在用 swagger 测试接口的时候添加头部信息
         */
        List<Parameter> pars = new ArrayList<>();
//        ParameterBuilder tokenPar = new ParameterBuilder();
//        ParameterBuilder refreshTokenPar = new ParameterBuilder();
//        tokenPar.name("authorization").description("登录之后返回的accessToken").modelRef(new ModelRef("string")).parameterType("header").required(true);
//        refreshTokenPar.name("refresh_token").description("登录之后返回的refreshToken").modelRef(new ModelRef("string")).parameterType("header").required(true);
//        /**
//         * 多个的时候 就直接添加到 pars 就可以了
//         */
//        pars.add(tokenPar.build());
//        pars.add(refreshTokenPar.build());
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(basePackage(basePackages))
                .paths(PathSelectors.any())
                .build()
                .globalOperationParameters(pars)
                .enable(enable)
                ;
    }


    /**
     * 声明基础包
     *
     * @param basePackage 基础包路径
     * @return
     */
    public static Predicate<RequestHandler> basePackage(final String basePackage) {
        return input -> declaringClass(input).transform(handlerPackage(basePackage)).or(true);
    }

    /**
     * 校验基础包
     *
     * @param basePackage 基础包路径
     * @return
     */
    private static Function<Class<?>, Boolean> handlerPackage(final String basePackage) {
        return input -> {
            for (String strPackage : basePackage.split(splitor)) {
                boolean isMatch = input.getPackage().getName().startsWith(strPackage);
                if (isMatch) {
                    return true;
                }
            }
            return false;
        };
    }

    /**
     * 检验基础包实例
     *
     * @param requestHandler 请求处理类
     * @return
     */
    @SuppressWarnings("deprecation")
    private static Optional<? extends Class<?>> declaringClass(RequestHandler requestHandler) {
        return Optional.fromNullable(requestHandler.declaringClass());
    }


    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("数据接口")
                .description("数据接口")
                .version("1.0")
                .build();
    }
}

二、swagger2.x注解规范

常用注解	使用说明
@Api(value = “”, tags = “”)	在controller类上使用，用于说明controller主要作用或者模块信息，tags 为标签信息，后边可以根据tags中内容生成YApi中接口目录
@ApiOperation(value = “”, notes = “”, consumes = “”, tags = “”, httpMethod = “”)	在接口方法上使用，用于描述接口信息，value可以用于描述接口简要信息；notes可以用于详细描述接口信息（参数信息，接口逻辑等）；consumes 用于说明接口传参方式（即Content-Type），常用值有：multipart/form-data（form表单传参方式）， application/json（JSON格式传参）；tags可为接口添加标签信息; httpMethod 说明接口请求方法，常用值有 POST，GET，PUT，DELETE，HEAD，OPTIONS
@ApiImplicitParam(name = “”, value = “”, required = true, paramType = “”)	在接口方法上使用该注解，用于说明请求参数。name参数的名称；value参数说明；required是否必填，true必填，false非必填；paramType请求参数传参方式，常用值有：path, query, body, header, form
@ApiModel(value = “”, description = “”)	当请求参数封装到类中时，可在类上使用该注解，用于说明封装类。value可用于给封装的类起别名，description 可用于描述封装类
@ApiModelProperty(value = “”, required = true)	在请求参数封装的类中的一个属性上使用，用于说明请求参数。value说明参数简要信息；required参数是否必填，true必填，false非必填；
@ApiResponse(code = 400, message = “参数为空”)	在接口上使用，用于标注接口的返回HTTP状态码和提示信息

1.form-data传参方式

需要在 @ApiOperation 注解中的consumes 指定传参方式为 multipart/form-data，此处设置consumes，是为了后边将接口数据导入到YApi，不设置consumes的话导入到YApi会不显示请求参数，Content-Type默认为 application/json。

@ApiOperation(value = "登录接口", notes = "此处为接口说明", consumes = "multipart/form-data", tags = "")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "account", value = "登录账号（邮箱或者手机号）", required = true, paramType = "form"),
            @ApiImplicitParam(name = "pass", value = "登录密码", required = true, paramType = "form")
    })
    @ResponseBody
    @RequestMapping(value = "/login", method = RequestMethod.POST)
    public Result<LoginResponseVO> login(String account, String pass){
        Result result = new Result();

        System.out.println("login account :====>>>> " + account);
        System.out.println("login pass :====>>>> " + pass);

        result.setCode("1");
        result.setMsg("success");

        LoginResponseVO loginResponseVO = new LoginResponseVO();
        loginResponseVO.setAge(18);
        loginResponseVO.setUserName("YCH");
        loginResponseVO.setSex(1);

        result.setData(loginResponseVO);

        return result;
    }

2.JSON格式传参

请求参数的封装类

package com.example.demo.common.vo;

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

@Data
@ApiModel(value = "添加用户请求参数", description = "添加用户请求参数描述信息---")
public class AddUserRequestVO {

    @ApiModelProperty(value = "用户名称", required = true)
    String userName;

    @ApiModelProperty(value = "用户年龄", required = true)
    Integer age;

    @ApiModelProperty(value = "用户性别，0保密；1男；2女", required = true)
    Integer sex;

}

返回参数的封装

package com.example.demo.common.vo;

import io.swagger.annotations.ApiModelProperty;
import lombok.Data;

@Data
public class Result <T>{

    @ApiModelProperty(value = "调用API返回状态码，1成功；-1失败", required = true)
    String code;

    @ApiModelProperty(value = "调用API返回提示信息", required = true)
    String msg;

    @ApiModelProperty(value = "调用API返回数据")
    T data;

}

package com.example.demo.common.vo;

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

@Data
@ApiModel(value = "登录响应参数")
public class LoginResponseVO {

    @ApiModelProperty(value = "用户名称", required = true)
    String userName;

    @ApiModelProperty(value = "用户年龄", required = true)
    Integer age;

    @ApiModelProperty(value = "用户性别，0保密；1男；2女", required = true)
    Integer sex;

}

接口方法

@ApiOperation(value = "添加用户", notes = "此处为接口说明")
    @ResponseBody
    @RequestMapping(value = "/user/add", method = RequestMethod.POST)
    public Result<LoginResponseVO> addUser(@RequestBody AddUserRequestVO addUserRequestVO){

        Result result = new Result();

        System.out.println("login addUserRequestVO :====>>>> " + addUserRequestVO);

        result.setCode("1");
        result.setMsg("success");

        LoginResponseVO loginResponseVO = new LoginResponseVO();
        loginResponseVO.setAge(18);
        loginResponseVO.setUserName("YCH");
        loginResponseVO.setSex(1);

        result.setData(loginResponseVO);

        return result;
    }

贴一下常用的几种接口入参方式

package com.example.demo.controller;

import com.example.demo.common.vo.AddUserRequestVO;
import com.example.demo.common.vo.LoginResponseVO;
import com.example.demo.common.vo.Result;
import io.swagger.annotations.*;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.*;

@Api(value = "用户管理", tags = "用户管理")
@Controller
@RequestMapping("/test")
public class TestSwaggerController {

    @ApiOperation(value = "添加用户", notes = "此处为接口说明")
    @ResponseBody
    @RequestMapping(value = "/user/add", method = RequestMethod.POST)
    public Result<LoginResponseVO> addUser(@RequestBody AddUserRequestVO addUserRequestVO){

        Result result = new Result();

        System.out.println("login addUserRequestVO :====>>>> " + addUserRequestVO);

        result.setCode("1");
        result.setMsg("success");

        LoginResponseVO loginResponseVO = new LoginResponseVO();
        loginResponseVO.setAge(18);
        loginResponseVO.setUserName("YCH");
        loginResponseVO.setSex(1);

        result.setData(loginResponseVO);

        return result;
    }

    @ApiOperation(value = "登录接口", notes = "此处为接口说明", consumes = "multipart/form-data", tags = "")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "account", value = "登录账号（邮箱或者手机号）", required = true, paramType = "form"),
            @ApiImplicitParam(name = "pass", value = "登录密码", required = true, paramType = "form")
    })
    @ResponseBody
    @RequestMapping(value = "/login", method = RequestMethod.POST)
    public Result<LoginResponseVO> login(String account, String pass){
        Result result = new Result();

        System.out.println("login account :====>>>> " + account);
        System.out.println("login pass :====>>>> " + pass);

        result.setCode("1");
        result.setMsg("success");

        LoginResponseVO loginResponseVO = new LoginResponseVO();
        loginResponseVO.setAge(18);
        loginResponseVO.setUserName("YCH");
        loginResponseVO.setSex(1);

        result.setData(loginResponseVO);

        return result;
    }

    @ApiOperation(value = "根据用户id获取用户信息", notes = "此处为接口说明")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "id", value = "用户id", required = true, paramType = "path"),
    })
    @ResponseBody
    @GetMapping("/user/{id}")
    public Result<LoginResponseVO> getUserInfo(@PathVariable(name = "id") Integer id){

        Result result = new Result();

        System.out.println("id is :====>>> " + id);

        result.setCode("1");
        result.setMsg("success");

        LoginResponseVO loginResponseVO = new LoginResponseVO();
        loginResponseVO.setAge(18);
        loginResponseVO.setUserName("YCH");
        loginResponseVO.setSex(1);

        result.setData(loginResponseVO);

        return result;
    }

    @ApiOperation(value = "根据用户id获取用户信息", notes = "此处为接口说明", httpMethod = "GET")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "id", value = "用户id", required = true, paramType = "query"),
    })
    @ApiResponses({
            @ApiResponse(code = 0, message = "")
    })
    @ResponseBody
    @RequestMapping(value = "/userinfo")
    public Result<LoginResponseVO> getUserInfo1(Integer id){

        Result result = new Result();

        System.out.println("id is :====>>> " + id);

        result.setCode("1");
        result.setMsg("success");

        LoginResponseVO loginResponseVO = new LoginResponseVO();
        loginResponseVO.setAge(18);
        loginResponseVO.setUserName("YCH");
        loginResponseVO.setSex(1);

        result.setData(loginResponseVO);

        return result;
    }

}

三、json格式数据导入到YApi

启动项目，如果项目没有设置 项目请求路径（context-path），则直接访问 http://IP:PORT/swagger-ui.html 即可看到swagger自带的页面。 如果设置了context-path，例： /test，则项目启动后访问 http://IP:PORT/test/swagger-ui.html 即可。

这里同一个接口出现多种请求方法的文档，是由于该接口方法上的注解 @ApiOperation(value = “”, notes = “”, consumes = “”, tags = “”, httpMethod = “”)没有指定httpMethod，并且spring注解使用的 @RequestMapping 没有指定 RequestMethod

访问 http://localhost:8080/test/v2/api-docs 即可获取swagger JSON格式的 接口数据

打开我们的YApi，在对应的项目中，找到数据管理，开启URL导入，复制 swagger JSON格式数据的请求地址，粘贴到url输入框，点击上传即可。

注：如果公司部署的YApi是外网环境，这里填写的url地址应该为外网能访问的地址；如果YApi部署的是内网环境，则这里填写内网IP才能成功导入，所以这里的localhost需要修改为我本机的内网IP地址（http://10.17.16.13:8080/test/v2/api-docs）

导入成功后