Swagger初学习笔记-CFANZ编程社区

文章目录

1.概念 & 在springboot中初步集成Swagger

Swagger :

最好的APi开源框架;支持多种语言,且可以在线测试接口;
仅需按照规范定义接口以及相关信息; 注意这里所说的接口就是前后端交流时的接口;
在开发新版本或者迭代版本的时候，只需更新Swagger描述文件，即可自动生成接口文档和客户端服务端代码，做到调用端代码、服务端代码以及接口文档的一致性。

官网地址: https://swagger.io/

导入依赖,集成

<!--集成swagger-->
<dependency>
	<groupId>io.springfox</groupId>
	<artifactId>springfox-swagger2</artifactId>
	<version>2.9.2</version>
</dependency>
<dependency>
	<groupId>io.springfox</groupId>
	<artifactId>springfox-swagger-ui</artifactId>
	<version>2.9.2</version>
</dependency>

当然还需要在yml配置文件中进行配置;

spring:
	mvc:
      pathmatch:
        matching-strategy: ANT_PATH_MATCHER

在这里插入图片描述

写个配置类简单试试;
注意重要注解@EnableSwagger2 开启swagger2;
这里的注解@Configuration不陌生了,就是标注当前类作为配置类;

@Configuration
@EnableSwagger2
public class SwaggerConfig {

}

为啥要访问这个页面?
在引用的swagger-ui中就有这个供访问的页面
在这里插入图片描述

2.基本配置学习

比如说基本的自定义信息;

配置Docket摘要对象,描述信息;

首先配置自定义文件描述信息ApiInfo
在自定义的类中

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    //配置Docket的bean实例;
    @Bean
    public Docket myDocket(){
        return new Docket(DocumentationType.SPRING_WEB)
                .apiInfo(myApi());
    }

    //可自定义配置swagger信息;
    public ApiInfo myApi(){
        //作者信息;
        Contact contact = new Contact("小智RE0","https://blog.csdn.net/MrTumnus","我的邮箱");

        return new ApiInfo(
                "这是API文档的标题",
                "这是我API文档的描述",
                "1.0",
                //组织链接;
                "http://localhost:8080/#/login",
                 //作者信息;
                 contact,
                "Apache 2.0",
                "https://www.bilibili.com/video/BV1Y441197Lw?p=2",
                new ArrayList());
    }
}

运行;可看到配置已生效
在这里插入图片描述

配置指定的扫描接口;
我们可看到它默认扫描了控制层的所有请求接口,扫描了所有的model实体类;
那么,怎么自定义设置呢?

比如我配置基本的扫描包

在这里插入图片描述

其他配置,比如配置扫描全部: any(); 配置什么都不扫描: none() ;
扫描类上的指定注解:withClassAnnotation;
扫描方法上的指定注解:withMethodAnnotation;

可使用paths()配置指定的过滤规则;

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    //配置Docket的bean实例;
    @Bean
    public Docket myDocket(){
        return new Docket(DocumentationType.SPRING_WEB)
                .apiInfo(myApi())
                .select()
                //注意这里可用 requestHandler 接口的实现类:RequestHandlerSelectors;配置扫描接口的方式;
                //首先配置指定的扫描包:basePackage()
                //.apis(RequestHandlerSelectors.basePackage("com.xiaozhi.backserver.startspringboot.controller"))
                //配置扫描全部: any()
                //.apis(RequestHandlerSelectors.any())
                //配置什么都不扫描: none()
                //.apis(RequestHandlerSelectors.none())
                //扫描类上的指定注解:withClassAnnotation
                .apis(RequestHandlerSelectors.withClassAnnotation(RestController.class))
                //扫描方法上的指定注解:withMethodAnnotation
                .apis(RequestHandlerSelectors.withMethodAnnotation(PostMapping.class))
                //配置过滤指定的路径:paths
                .paths(PathSelectors.ant("/api/admin/**"))
                .build();
    }

    //可自定义配置swagger信息;
    public ApiInfo myApi(){
        //作者信息;
        Contact contact = new Contact("小智RE0","https://blog.csdn.net/MrTumnus","我的邮箱");

        return new ApiInfo(
                "这是API文档的标题",
                "这是我API文档的描述",
                "1.0",
                //组织链接;
                "http://localhost:8080/#/login",
                 //作者信息;
                 contact,
                "Apache 2.0",
                "https://www.bilibili.com/video/BV1Y441197Lw?p=2",
                new ArrayList());
    }
}