Swagger2 3.0的使用

前言

今天使用了以下swagger2 的3.0.0版本，好家伙，好多坑。在这里记录一下，方便查阅。

一、Swagger的简介

官网：https://swagger.io/

Swagger 是一个规范且完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。

Swagger 的目标是对 REST API 定义一个标准且和语言无关的接口，可以让人和计算机拥有无须访问源码、文档或网络流量监测就可以发现和理解服务的能力。当通过 Swagger 进行正确定义，用户可以理解远程服务并使用最少实现逻辑与远程服务进行交互。与为底层编程所实现的接口类似，Swagger 消除了调用服务时可能会有的猜测。
非常适合前后分离的项目，后端人员提供swagger页面，前端使用，比接口文档更加方便。

Tips：
springboot 与 swagger有版本兼容问题，springboot 2.7.x版本不能使用swagger2
2.x版本，需要升级为3.x版本。 当然，条件允许，也可以降低springboot的版本为2.5.x版本。

二、基本使用

1、导入依赖

		<!--swagger2-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-boot-starter</artifactId>
            <version>3.0.0</version>
        </dependency>

2、修改yml

spring:
  mvc:
    pathmatch:
      matching-strategy: ant_path_matcher

3、创建config

如果这些信息不需要修改，可以不创建当前config，直接在主程序上写@EnableOpenApi配置即可。

@Configuration
@EnableOpenApi
public class SwaggerConfig {
    @Bean
    public Docket apiConfig() {
        return new Docket(DocumentationType.SWAGGER_2)
                //获取接口信息
                .apiInfo(getApiInfo())
                //指定主机域名，填写域名后，各个请求都会使用到域名
//                .host("https://www.zhangdl.cn/")
                //分组
                .groupName("systemManager")
                .select()
                //扫描指定位置
                .apis(RequestHandlerSelectors.basePackage("cn.zhangdl.tech_training.controller"))
                //-------- 指定扫描路径 --------
                .paths(PathSelectors.any())
                .build();
    }


    private ApiInfo getApiInfo() {
        return new ApiInfoBuilder()
                //标题
                .title("系统接口文档")
                //描述
                .description("此文档为系统接口说明，配置及相关注解")
                //许可证
                .license("Swagger2 api")
                //许可证地址
                .license("https://www.github.com")
                //服务条款地址
                .termsOfServiceUrl("https://www.spring.io")
                //版本
                .version("1.0.0")
                //维护人信息
                .contact(new Contact("zhangdl", "https://blog.csdn.net/qq_41404112", "zhangdl945@163.com"))
                .build();
    }
}

4、业务controller

@RestController
@Api(tags = "项目前的环境测试接口")
public class TestController {

	@ApiOperation(value = "测试Swagger")
    @GetMapping("hello")
    public String hello(){
        return "hello";
    }
}

5、查看swagger接口页面

访问路径：http://localhost:8080/swagger-ui/index.html
相较于swagger2 2.x版本，路径也有变化哦

三、其他功能

这里会记录一些swagger的其他功能介绍，后面补充。