一、前言

Swagger是一个规范和完整的框架,用于生成、描述、调用和可视化RESTful风格的Web服务。目标是使客户端和文件系统作为服务器以同样的速度来更新文件的方法,参数和模型紧密集成到服务器。

Swagger能够在线自动生成 RESTFul接口的文档，同时具备测试接口的功能。

简单点来讲就是说，Swagger是一款可以根据RESTFul风格生成的生成的接口开发文档，并且支持做测试的一款中间软件。不是RESTFul风格也能生成文档。

二、集成SpringBoot

1.添加依赖

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

2.启动类加上@EnableSwagger2注解

package com.example.bootdemo;

import org.mybatis.spring.annotation.MapperScan;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@SpringBootApplication
@MapperScan("com.example.bootdemo.mapper")
@EnableSwagger2
public class BootDemoApplication {

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

}

3.application.properties配置

#路径匹配规则
spring.mvc.pathmatch.matching-strategy=ant_path_matcher

4.Swagger配置

以下主要是Swagger文档头部的一些信息设置。

package com.example.bootdemo.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;

/**
 * @author qx
 * @date 2023/12/16
 * @desc Swagger自定义配置
 */
@Configuration
public class SwaggerConfig {
    @Bean
    public Docket docket() {
        Docket docket = new Docket(DocumentationType.SWAGGER_2);
        ApiInfo apiInfo = new ApiInfoBuilder()
                // 标题
                .title("我是标题")
                // 版本
                .version("1.0")
                // 描述
                .description("项目描述")
                // 联系人
                .contact(new Contact("qx", "http://xxx.com", "xx@qq.com"))
                .build();
        return docket.apiInfo(apiInfo);
    }
}

5.创建控制层

创建一个带有2个参数的请求方法。

package com.example.bootdemo.controller;

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

/**
 * @author qx
 * @date 2023/12/16
 * @desc 控制层
 */
@RestController
public class TestController {

    @GetMapping("/index")
    public String hello(String name, Integer age) {
        return "my name is " + name + ",age is " + age;
    }
    
}

6.测试

我们启动项目，然后浏览器访问http://localhost:8080/swagger-ui.html

我们可以在这里面进行接口的调试。

SpringBoot集成Swagger的使用_Swagger

然后点击进行测试

SpringBoot集成Swagger的使用_Swagger_02

我们输入参数然后点击Execute就可以继续测试了。

SpringBoot集成Swagger的使用_SpringBoot_03

最后我们在Server response查看到请求返回的相关数据。

SpringBoot集成Swagger的使用_SpringBoot_04

三、Swagger注解的相关学习

我们可以学习Swagger相关的一些注解，丰富我们的Swagger测试。

@Api:用于类上，说明该类的作用。

@ApiModel:用在类上，表示对类进行说明，用于实体类中的参数接收说明。

@ApiOperation:用于对方法的说明。

@ApiModelProperty:用于字段、表示对属性的说明

@ApiImplicitParams和@ApiImplicitParam：用于对方法中的参数进行说明

name：参数名，对应方法中单独的参数名称。

• value：参数中文说明。

• required：是否必填。

• paramType：参数类型，取值为 path、query、body、header、form。

• dataType：参数数据类型。

• defaultValue：默认值。

我们在刚才的测试类中添加相关的注解。

package com.example.bootdemo.controller;

import io.swagger.annotations.*;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

/**
 * @author qx
 * @date 2023/12/16
 * @desc 控制层
 */
@RestController
@ApiModel(value = "TestController", description = "测试接口")
public class TestController {

    @GetMapping("/index")
    @ApiOperation(value = "测试", notes = "描述")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "name", value = "用户姓名", dataType = "string", paramType = "query", required = true, defaultValue = ""),
            @ApiImplicitParam(name = "age", value = "用户年龄", dataType = "int", paramType = "query", required = true, defaultValue = "1")
    })
    public String hello(String name, Integer age) {
        return "my name is " + name + ",age is " + age;
    }

}

我们重新启动程序然后打开Swagger地址。

SpringBoot集成Swagger的使用_SpringBoot_05

这样我们可以更方便的进行测试。比如我们没有传入方法中必须要传入的参数，Swagger会很友好的提示出来。

SpringBoot集成Swagger的使用_Swagger_06