什么是swagger2

swagger2就是api接口，它可以对自己书写的接口进行说明，并以文档的形式存在。

为什么要使用swagger2接口文档？

1. 接口测试与调试：Swagger2 提供了一个可交互的 UI 界面，可以方便地进行接口测试和调试，同时展示接口的输入参数、输出参数、返回类型、请求方式等详细信息，使得开发人员更加清晰地了解 API 接口的使用。
2. 接口可视化：Swagger2 的 UI 界面提供了强大的接口可视化功能，可以对接口进行分类、分组、标记、描述等，便于开发人员快速了解接口的用途和功能。
3. 接口管理：Swagger2 可以将项目中所有的 API 接口集中管理，方便开发人员快速查找和了解接口的使用方式和定义规范，也有助于团队协作和代码维护。

如何使用swagger2

(1) 引入swagger2的依赖

<!--swagger的依赖引入-->
<dependency>
    <groupId>io.github.jianzhichun</groupId>
    <artifactId>spring-boot-starter-swagger2</artifactId>
    <version>0.0.1</version>
</dependency>
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>swagger-bootstrap-ui</artifactId>
    <version>1.9.6</version>
</dependency>

(2)配置swagger2的信息

@Configuration  //类似于文件配置，表示这个类是一个配置类
public class MySwaggerConfig {

    /**
     * groupName()  设置API分组名称
     * apiInfo()  设置API文档的基本信息，如标题，版本等等
     * select():  该对象用于指定要扫描哪些API接口
     *apis():     指定要扫描的API接口，可以根据包路径，注解等进行过滤。
     *                            按包路径过滤 API 接口： RequestHandlerSelectors.basePackage("com.example.controller")
     *                            按注解过滤 API 接口： RequestHandlerSelectors.withMethodAnnotation(GetMapping.class)
     *  build() 调用 build() 方法生成一个 ApiSelectorBuilder 对象，该对象包含了所有的配置信息和扫描规则用于生成 Swagger API 文档
     *
     * @return
     */
    @Bean  //加载方法上，表示把返回的结果交给spring容器管理，里面封装了接口文档的信息
    public Docket docket(){
        final Docket docket = new Docket(DocumentationType.SWAGGER_2)
                .groupName("cjj小组")  //小组名称
                .apiInfo(getInfo())
                .select().apis(RequestHandlerSelectors.basePackage("com.example.controller")).build();
        return docket;
    }
    /**
     * this.title = title; todo API的标题
     *         this.description = description;  todo API的描述
     *         this.version = version;todo API版本
     *         this.termsOfServiceUrl = termsOfServiceUrl;todo 服务条款URL
     *         this.contact = contact;todo 联系人信息，包括联系人姓名，联系人URL，联系人电子邮箱等等
     *         this.license = license;todo API的许可信息
     *         this.licenseUrl = licenseUrl;todo API的许可URL
     * @return
     */
    private ApiInfo getInfo(){
        //给contact赋值
        Contact contact = new Contact("cjj", "www.jd.com", "1094595654@qq.com");
        ApiInfo apiInfo = new ApiInfo("cjj的springboot001接口文档","这里记录了第一次使用swagger文档",
               "1.0","https://www.baidu.com",contact,"jj科技网络有限公司","www.jj.com");
        return apiInfo;
    }
}

启动工程并访问swagger接口文档的路径

http://ip地址:端口号/swagger-ui.html

http://ip:端口号/doc.html

(3)使用swagger的注解

@Api(tags=""):加载接口Controller类上，他是对接口类的说明

@ApiOperation(value=""): 加载接口方法上，他是对接口方法的说明

@ApiImplicitParams: 他是对接口所有参数的说明，用在方法上

@ApiImplicitParam：它是对单个参数的说明，用在ApiImplicitParams里面

里面的参数有：name:参数名；

value：参数描述；

dataType：数据类型；

paramType：参数类型，可以是header、query、path、formData或body；

required：参数是否必填。默认是false；

defaultValue：参数书的默认值；

allowableValues：参数允许的值的范围；

access：参数的访问权限；

@ApiModel:它是对实体类的说明；

@ApiModelProperty：它是对实体类中属性的说明；