【快速上手系列】使用Springboot集成Swagger2的简单使用测试

【快速上手系列】使用Springboot集成Swagger2的简单使用测试

简介

Swagger2是为了解决企业中接口（api）中定义统一标准规范的文档生成工具。 尤其是前后端分离时对一些业务接口也不太方便，接下来进行一下简单的使用测试。

使用步骤

创建一个springboot项目，如果你不会创建可以看这里：【快速搭建系列】idea傻瓜式快速搭建springboot框架

1、导入jar包

添加maven依赖

pom.xml

<!--swagger2依赖-->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>
<!--视图逻辑swagger-ui-->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

2、添加注解

在springboot启动类添加@EnableSwagger2注解

/**
 * @Author Tuerlechat,
 * @Date 2022/12/5
 */
@SpringBootApplication
@EnableSwagger2 //开启swagger2
public class Swagger2 {
    public static void main(String[] args) {
        SpringApplication.run(Swagger2.class,args);
    }
}

tips：@EnableSwagger2会扫描当前类所在包，及子包中所有的类型中的注解（毕竟都放到启动类上了😂）

3、创建需要访问的类

我这里创建了一个测试的controller

IndexController.java

/**
 * @Author Tuerlechat,
 * @Date 2022/12/5
 */
@Api(tags = "swagger2测试")	//自定义一个类的标签名，在页面接口处显示
@RestController
public class IndexController {

        @ApiOperation(value = "用于测试post请求")	//测试接口的解释
        @PostMapping("/imPost") //post请求
        public String imPost(String str) {
            return "我是post请求，str==" + str;
        }

        @ApiOperation(value = "用于测试get请求")	
        @GetMapping("/imGet") //get请求
        public String imGet(String str) {
            return "我是get请求，str==" + str;
        }

        @RequestMapping("/imRequest")  //这种请求方式是不限制请求方式的，任意请求方式都可以访问
        public String imRequest(String str) {
            return "我是RequestMapping，str==" + str;
        }
}

然后我们启动服务器

访问 Swagger UI

然后可以看到成功显示页面，我们可以在上面看到自己写的相应接口信息

解释

图上三个方框分别是我写的三个controller方法

接口上也有相应的一些访问路径

可以看到标题对应了类上的@Api(tags = "xxxx")注解，右边是我写接口的类名

请求接口的方法对应了方法中的@ApiOperation(value = "xxxx")注解，在接口的右面进行接口的一些相应解释

Get请求和Post请求因为设定了所以都是一个

RequestMapping因为没有对请求进行限制，所以显示出了相应请求的所有接口

点击相应的接口可以看到上面显示接口的参数和响应信息，然后我们可以点击Try it out来测试接口参数

然后在参数中输入值，点击Execute来执行，查看接口返回响应结果即可

tips：上面显示了一些命令和请求头等信息，绿色框上可以看到接口的请求url

设置配置文件来进行一些自定义操作

创建一个swagger2配置类来进行一些自定义操作

SwaggerConfig.java

/**
 * @Author Tuerlechat,
 * @Date 2022/12/5
 */
@Configuration  //设置配置类
@EnableSwagger2	//开启swagger2
public class SwaggerConfig {

    @Bean
    public Docket webApiConfig(){

        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("主页api接口")    //起一个分组名
                .apiInfo(webApiInfo())  //添加下面对应的方法
                .select()
                //过滤掉admin路径下的所有页面
                .paths(Predicates.not(PathSelectors.regex("/admin/.*")))
                //过滤掉所有error或error.*页面（默认有一个error页面）
                .paths(Predicates.not(PathSelectors.regex("/error.*")))
                .build();

    }

    @Bean
    public Docket adminApiConfig(){

        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("管理员api接口")  //起一个分组名
                .apiInfo(adminApiInfo())    //添加下面对应的方法
                .select()
                //只显示admin路径下的页面
                .paths(Predicates.and(PathSelectors.regex("/admin/.*")))
                .build();

    }

    /**
     * 对应上面的实现方法
     * @return
     */
    private ApiInfo webApiInfo(){

        return new ApiInfoBuilder()
                .title("swagger2—测试API文档")  //标题
                .description("本文档描述了对swagger2进行使用测试")   //描述
                .version("1.3") //版本
                //网站访问跳转链接和发送邮箱
                .contact(new Contact("我的主页",
                        "https://blog.youkuaiyun.com/weixin_55452293?spm=1010.2135.3001.5343",
                        "111111@qq.com"))
                .build();
    }

    /**
     * 对应上面的实现方法
     * @return
     */
    private ApiInfo adminApiInfo(){

        return new ApiInfoBuilder()
                .title("swagger2-测试使用API文档2")
                .description("本文档描述了对swagger2进行使用测试的一些信息")
                .version("1.0")
                .contact(new Contact("管理员admin", "https://blog.youkuaiyun.com/weixin_55452293?spm=1010.2135.3001.5343", "111111@qq.com"))
                .build();
    }

}

然后再创建一个controller用于测试

AdminController.java

/**
 * @Author Tuerlechat,
 * @Date 2022/12/5
 */
@Api(tags = "admin测试")
@RestController
@RequestMapping("/admin")
public class AdminController {

    @ApiOperation(value = "这是admin接口测试")
    @PostMapping("/imAdmin") //post请求
    public String imAdmin(@ApiParam(name = "str", value = "张三", required = true) String str) {
        return "我是admin接口。";
    }

}

然后运行服务器，访问或刷新 Swagger UI

可以看到相应的显示信息都改变了

然后可以点击右上角的分组类别来选中管理员api接口

可以看到相应的信息也更改了

这样就可以了🤓