springboot项目配置添加swagger

目录

简介：

第一步：在pom文件中引入swagger的依赖

第二步：编写swagger的config配置类

第三步：编写后端接口

---

简介：

       在前后端分离的项目中，前后端是分开开发的，很多时候后端已经开发完成，但是前段仍然没有完成；

这个时候，后端需要对自己开发的接口进行测试，目前可以通过postman来进行。但是这及其不方便，还需

要下载一个postman软件。

       又或者当前端找后端开发人员了解后端的接口有哪些，接口中的入参出参是什么，这个时候，后端人员

就需要编写一份接口文档，里面整理各个接口以及其入参与出参；或者在开发的过程中就编写接口文档

或者在编写完成后一个一个的补充编写接口文档。

       那么，有没有什么更好的方式来解决如上的两个问题的，答案当然是有！Swagger应运而生！只要在咱

们开发的springboot项目中引入Swagger，不但可以让自己很方便的进行接口自测，也可以很简单的告诉前

端开发人员，后端接口有哪些，各接口的入参与出参是什么，那么接下来咱们就开始在项目中加入swagger吧。

第一步：在pom文件中引入swagger的依赖

1. 在pom文件的properties中增加swagger版本号设置，如果没有properties可自行增加，也可跳过此步

 <swagger.version>2.9.2</swagger.version>

2. 在pom文件的dependencies下增加swagger的两个依赖引入

        <!-- swagger工具包引入 -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>${swagger.version}</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>${swagger.version}</version>
        </dependency>

如果为进行 1的设置，此处${swagger.version}直接填入swagger的版本号即可

第二步：编写swagger的config配置类

1. 在自己的项目中新建一个config包（如有可不管，不建也可，只是为了规范与结构）

2. 然后新建类SwaggerConfig.java（也可自己随意命名），编写swagger的相关配置

3. 编写swagger配置类，配置swagger的扫描路径、所有请求加请求头、编写api接口文档相关的信息

import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.ParameterBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.schema.ModelRef;
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;

/**
  * Swagger配置类
  * @author kevin
  * @date 2020/12/23
  */
@EnableSwagger2
@Configuration
public class SwaggerConfig {
    @Value("${swagger.enable:false}")
    private boolean enableSwagger;

    /**
      * swagger2的配置文件，这里可以配置swagger2的一些基本的内容，比如扫描的包等等
      * @author kevin
      * @return springfox.documentation.spring.web.plugins.Docket
      * @date 2021/1/26 14:14
      */
    @Bean
    public Docket createRestApi() {
        ParameterBuilder ticketPar = new ParameterBuilder();
        List<Parameter> pars = new ArrayList<>();
        //设置所有接口的请求头
        ticketPar.name("token").description("用户token信息")
                .modelRef(new ModelRef("string")).parameterType("header")
                //header中的ticket参数非必填，传空也可以
                .required(false).build();
        pars.add(ticketPar.build());    //根据每个方法名也知道当前方法在设置什么参数

        return new Docket(DocumentationType.SWAGGER_2)
                //接扣文档的相关信息
                .apiInfo(apiInfo())
                //配置是否启用swagger
                .enable(enableSwagger)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.liu.test"))
                .paths(PathSelectors.any())
                .build()
                .globalOperationParameters(pars);
    }

    /**
      * api文档的详细信息函数
      * @author kevin
      * @return springfox.documentation.service.ApiInfo
      * @date 2021/1/26 14:12
      */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("自己玩儿项目")
                .description("自己玩儿项目API文档")
                .version("1.0.0")
                .contact(new Contact("kevin", "https://blog.csdn.net/liu649983697", "649983697@qq.com"))
                .build();
    }

 

第三步：编写后端接口

1. 在接口目录下，新增HelloController.java

在类上加上swagger注解

@Api(value = "HelloController", tags = "测试相关接口")

2. 增加入参实体类ApplyTwoNumberRequest

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

@ApiModel(value = "ApplyTwoNumberRequest", description = "两个数字加减乘除运算")
public class ApplyTwoNumberRequest {
    @ApiModelProperty(name = "first", value = "第一个数字", example = "55")
    private int first;
    @ApiModelProperty(name = "second", value = "第二个数字", example = "55")
    private int second;
    @ApiModelProperty(name = "operator", value = "加减乘除操作中的一个（add,sub,multiply,divide）", example = "multiply")
    private String operator;

    public int getFirst() {
        return first;
    }

    public void setFirst(int first) {
        this.first = first;
    }

    public int getSecond() {
        return second;
    }

    public void setSecond(int second) {
        this.second = second;
    }

    public String getOperator() {
        return operator;
    }

    public void setOperator(String operator) {
        this.operator = operator;
    }
}

3.增加出参实体类ApplyTwoNumberResponse

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

@ApiModel(value = "ApplyTwoNumberResponse", description = "两个数字加减乘除运算结果")
public class ApplyTwoNumberResponse {
    @ApiModelProperty(name = "applyResult", value = "计算结果", example = "11")
    private double applyResult;
    @ApiModelProperty(name = "operateType", value = "计算方式", example = "相除")
    private String operateType;

    public double getApplyResult() {
        return applyResult;
    }

    public void setApplyResult(double applyResult) {
        this.applyResult = applyResult;
    }

    public String getOperateType() {
        return operateType;
    }

    public void setOperateType(String operateType) {
        this.operateType = operateType;
    }
}

4. 增加接口方法test

/**
      * 根据传入的两个数字，与运算类型，进行加减乘除运算
      * @author kevin
      * @param request :
      * @return java.lang.Double
      * @date 2021/1/26 13:56
      */
    @ApiOperation(value = "两个数字加减乘除（add,sub,multiply,divide）", notes = "mathApply")
    @PostMapping("/mathApply")
    public ApplyTwoNumberResponse applyTwoNumber(ApplyTwoNumberRequest request) {
        int first = request.getFirst();
        int second = request.getSecond();
        String operator = request.getOperator();
        double applyResult;
        String opType = "";
        if ("add".equals(operator)) {
            applyResult = first + second;
            opType = "相加";
        } else if ("multiply".equals(operator)) {
            applyResult = first * second;
            opType = "相乘";
        } else if ("divide".equals(operator)) {
            applyResult = first / second;
            opType = "相除";
        } else if ("subtract".equals(operator)) {
            applyResult = first - second;
            opType = "相减";
        }
        ApplyTwoNumberResponse result = new ApplyTwoNumberResponse();
        result.setApplyResult(applyResult);
        result.setOperateType(opType);
        return result;
    }

5. 启动项目，进行测试 

项目启动后，访问 http://ip:port/contextpath/swagger-ui.html

打开hello-controller即可看到接口及出入参情况：

6. 点击接口里的try it out，输入入参，然后点击execute运行进行接口测试