Swagger初学习笔记

Swagger初学习笔记

学习来源 B站:狂神说:【狂神说Java】一小时掌握Swagger技术

文章目录

1.概念 & 在springboot中初步集成Swagger2.基本配置学习3.配置APi文档的分组,接口注释...

---

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

---

Swagger :

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

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

导入依赖,集成

	io.springfox
	springfox-swagger2
	2.9.2


	io.springfox
	springfox-swagger-ui
	2.9.2

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

spring:
	mvc:
      pathmatch:
        matching-strategy: ANT_PATH_MATCHER

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

@Configuration
@EnableSwagger2
public class SwaggerConfig {

}

访问http://localhost:5277/swagger-ui.html;(注意我这里的本地当前后端服务端口设为了5277);
这个查看效果确实很方便呢

为啥要访问这个页面?
在引用的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());
    }
}

运行后

可配置是否自动启动;在Docket对象初始化时enabled属性默认为true;

`
配置试试

运行启动后;

---

那么如何配置swagger在生产环境中生效,实际发布时不生效呢?

首先判断是不是生产环境;比如说使用一个标记值 flag;然后将flag传入到 enable(flag)中作为方法参数;来达到是否生效的效果;

在这里插入图片描述

启动;
访问http://localhost:5277/dev/swagger-ui.html#/

但是没有启动的测试环境,无法访问;

---

3.配置APi文档的分组,接口注释…

---

在自定义创建Docket对象时;使用groupName("组名")方法来定义分组的名称;
比如说定义不同的Docket对象 ;定义不同的分组名称;

启动后,可以注意到这里可以查看不同的组

---

关于实体Model类配置;
注意:只要在接口的返回值中包含了实体类,那么该实体类就会被扫描到;
比如这里登录时返回了Admin类

那么该类就被扫描到了;

还可以给实体类加文档注释;
在实体类上使用注解@ApiModel("文档注释");注释类信息;
可在属性上使用@ApiModelProperty("注释")在说明属性;

可在控制类处使用@Api(tags = "登录控制层") 标注当前的控制类;
方法处使用@ApiOperation("注释")标注当前接口注释;
可在方法参数使用@ApiParam(" ") 标注当前的方法参数含义;

---