Swagger笔记

最新推荐文章于 2022-03-15 17:07:20 发布

跪下，大胆刁民

最新推荐文章于 2022-03-15 17:07:20 发布

阅读量1k

点赞数

分类专栏：笔记文章标签： swagger2

本文链接：https://blog.csdn.net/qq_45886944/article/details/119112106

版权

笔记专栏收录该内容

48 篇文章 0 订阅

订阅专栏

Swagger

Swagger简介

前后端分离

前端 -> 前端控制层、视图层
后端 -> 后端控制层、服务层、数据访问层
前后端通过API进行交互
前后端相对独立且松耦合

产生的问题

前后端集成，前端或者后端无法做到“及时协商，尽早解决”，最终导致问题集中爆发

解决方案

首先定义schema [ 计划的提纲 ]，并实时跟踪最新的API，降低集成风险
早些年：指定wor计划文档；
前后端分离：
- 前端测试厚度那接口：postman
- 后端提供接口，需要实时更新最新的消息即改动

Swagger

号称世界上最流行的API框架
Restful Api 文档在线自动生成器 => API 文档与API 定义同步更新
直接运行，在线测试API
支持多种语言（如：Java，PHP等）
官网：https://swagger.io/

swagger使用

配置Swagger

第一步：

新建一个普通的springboot项目工程，并把创建好的项目中一些不需要的文件删了

第二步：

使用 Swagger2 工具，必须要导入 maven 依赖.

  <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>

第三步

新建一个与主程序平级的Controller包,并建立一个类

代码：

@RestController
public class HelloController {
    @GetMapping("/hello")
    public String hello(){
        return "hello";
    }
}

第四步

使用 Swagger2 需要进行配置，Spring Boot 中对 Swagger2 的配置非常方便，新建一个配置类，Swagger2 的配置类上除了添加必要的 @Configuration 注解外，还需要添加 @EnableSwagger2 注解。

@Configuration
@EnableSwagger2    //开启swagger2
public class SwaggerConfig {

}

第五步

访问测试：http://localhost:8080/swagger-ui.html ，可以看到swagger的界面；

第六步

1、Swagger实例Bean是Docket，所以通过配置Docket实例来配置Swaggger。

@Bean //配置docket以配置Swagger具体参数
public Docket docket() {
   return new Docket(DocumentationType.SWAGGER_2);
}

ctrl+鼠标左键点击Docket查看它的源码，再次ctrl+鼠标左键点击DocumentationType查看源码

2、通过apiInfo()属性配置文档信息，并在Docket 实例关联上 apiInfo()

ctrl+鼠标左键点击Docket查看它的源码，再次ctrl+鼠标左键点击ApiInfo查看源码

2021-07-26_113955

@Configuration
@EnableSwagger2    //开启swagger2
public class SwaggerConfig {
    @Bean //配置docket以配置Swagger具体参数
    public Docket docket() {
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo());
    }

    private ApiInfo apiInfo() {
        Contact contact = new Contact("大胆刁民", "https://blog.csdn.net/qq_45886944/category_10575369.html?spm=1001.2014.3001.5482", "2595915122@qq.com");
        return new ApiInfo(
                "Swagger学习", // 标题
                "想的不可得，你奈人生何。", // 描述
                "v1.0", // 版本
                "https://blog.csdn.net/qq_45886944/category_10575369.html?spm=1001.2014.3001.5482", // 组织链接
                contact, // 联系人信息
                "Apache 2.0 许可", // 许可
                "许可链接", // 许可连接
                new ArrayList<>() // 扩展
        );
    }
}

3、重启项目，访问测试 http://localhost:8080/swagger-ui.html 看下效果

673gif

配置扫描接口

@Configuration
@EnableSwagger2    //开启swagger2
public class SwaggerConfig {
    @Bean //配置docket以配置Swagger具体参数
    public Docket docket() {
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
                .produces(Collections.singleton("application/json"))
                .consumes(Collections.singleton("application/json"))
                .protocols(Collections.singleton("http"))
                .select()             //select()函数返回一个ApiSelectorBuilder实例用来控制哪些接口暴露给Swagger来展现
                //RequestHandlerSelectors配置扫面接口的方式
                //RequestHandlerSelectors.basePackage("包名") 指定扫描的包路径
                //RequestHandlerSelectors.any()扫描全部
                //RequestHandlerSelectors.none()都不扫描
                .apis(RequestHandlerSelectors.basePackage("com.zsq.Controller"))      //指定扫描的包路径

                //.paths()过滤什么路径
                //.paths()。any() 任何请求都扫描
                //.paths()。none()任何请求都不扫描
                //.paths()。regex(final String pathRegex) 通过正则表达式控制
                //.paths()。ant(final String antPattern) 通过ant()控制
                .paths(PathSelectors.ant("/zsq/**"))       //Swagger会扫描Controller包下的所有路径带有以/zsq开头的路径
                .build();
    }

    private ApiInfo apiInfo() {
        // 联系人信息(姓名 网站地址 邮箱)
        Contact contact = new Contact("大胆刁民", "https://blog.csdn.net/qq_45886944/category_10575369.html?spm=1001.2014.3001.5482", "2595915122@qq.com");
        return new ApiInfo(
                "Swagger学习", // 标题
                "想的不可得，你奈人生何。", // 描述
                "v1.0", // 版本
                "https://blog.csdn.net/qq_45886944/category_10575369.html?spm=1001.2014.3001.5482", // 组织链接
                contact, // 联系人信息
                "Apache 2.0 许可", // 许可
                "许可链接", // 许可连接
                new ArrayList<>() // 扩展
        );
    }
}

演示：

674gif

配置Swagger开关

通过enable()方法配置是否启用swagger，如果是false，swagger将不能在浏览器中访问了

 @Bean
public Docket docket(Environment environment) {
   return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
 .enable(false) //配置是否启用Swagger，如果是false，在浏览器将无法访问
       // 省略配置....
}

演示：

676gif

配置API分组

单组：

如果没有配置分组，默认是default。通过groupName()方法即可配置分组：

@Bean
public Docket docket(Environment environment) {
   return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
      .groupName("hello") // 配置分组，默认组叫default
       // 省略配置....
}

源码：

单个组演示：

677gif

多组

配置多个分组只需要配置多个docket即可,然后其他的配置信息也需要自己写，不写就是默认的（通常一个人是一组，各写各的配置信息）

@Configuration
@EnableSwagger2    //开启swagger2
public class SwaggerConfig {
    @Bean //配置docket以配置Swagger具体参数
    public Docket docket() {
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
                .produces(Collections.singleton("application/json"))
                .consumes(Collections.singleton("application/json"))
                .protocols(Collections.singleton("http"))
                .enable(true) //配置是否启用Swagger，如果是false，在浏览器将无法访问
                .groupName("大胆刁民")
                .select()             //select()函数返回一个ApiSelectorBuilder实例用来控制哪些接口暴露给Swagger来展现
                //RequestHandlerSelectors配置扫面接口的方式
                //RequestHandlerSelectors.basePackage("包名") 指定扫描的包路径
                //RequestHandlerSelectors.any()扫描全部
                //RequestHandlerSelectors.none()都不扫描
                .apis(RequestHandlerSelectors.basePackage("com.zsq.Controller"))      //指定扫描的包路径

                //.paths()过滤什么路径
                //.paths()。any() 任何请求都扫描
                //.paths()。none()任何请求都不扫描
                //.paths()。regex(final String pathRegex) 通过正则表达式控制
                //.paths()。ant(final String antPattern) 通过ant()控制
                .paths(PathSelectors.ant("/zsq/**"))       //Swagger会扫描Controller包下的所有路径带有以/zsq开头的路径
                .build();
    }
    @Bean
    public Docket docket1(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("group1");
    }
    @Bean
    public Docket docket2(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("group2");
    }
    @Bean
    public Docket docket3(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("group3");
    }

    private ApiInfo apiInfo() {
        // 联系人信息(姓名 网站地址 邮箱)
        Contact contact = new Contact("大胆刁民", "https://blog.csdn.net/qq_45886944/category_10575369.html?spm=1001.2014.3001.5482", "2595915122@qq.com");
        return new ApiInfo(
                "Swagger学习", // 标题
                "想的不可得，你奈人生何。", // 描述
                "v1.0", // 版本
                "https://blog.csdn.net/qq_45886944/category_10575369.html?spm=1001.2014.3001.5482", // 组织链接
                contact, // 联系人信息
                "Apache 2.0 许可", // 许可
                "许可链接", // 许可连接
                new ArrayList<>() // 扩展
        );
    }
}

多组演示：

678gif

常用注解

API	API常用参数	作用位置
@Api	@Api(tags = {“tag1”,“tag2”,"…"})	controller类
@ApiOperation	@ApiOperation(value = “功能描述”,notes = “备注”)	controller类的方法
@ApiModel	@ApiModel(value=“类名”,description=“类描述”)	返回对象类
@ApiModelProperty	@ApiModelProperty(value = “类属性描述”,required = true,example = “属性举例”,notes = “备注”)	出入参数对象的字段
@ApiImplicitParams	@ApiImplicitParams({@ApiImplicitParam(),@ApiImplicitParam(),…})	controller的方法
@ApiImplicitParam	@ApiImplicitParam(name = “参数名”,value = “参数描述”,required = true,paramType = “接口传参类型”,dataType = “参数数据类型”)	@ApiImplicitParams的方法里用
@ApiResponses	@ApiResponses({ @ApiResponse(),@ApiResponse(),…})	controller的方法
@ApiResponse	@ApiResponse(code = 10001, message = “返回信息”)	@ApiResponses里用
@ApiIgnore	@ApiIgnore	类，方法，方法参数

新建实体类：

@Data
@AllArgsConstructor
@NoArgsConstructor
@ApiModel("用户类")
public class Person {
    @ApiModelProperty("姓名")
    private String name;
    @ApiModelProperty("密码")
    private int password;
}

在控制类上新增一个方法

@RestController
@Api(tags = "控制类")
public class HelloController {
    @ApiOperation("欢迎")
    @GetMapping("/zsq/hello")
    public String hello(){
        return "hello";
    }
    
    @ApiOperation("查询用户")
    @PostMapping("/zsq/adduser")
    public Person user(String username, int pwd){
        Person person = new Person();
        person.setName(username);
        person.setPassword(pwd);
        return person;
    }
}

演示注解的注释作用和模拟传参

680gif

Knife4j

项目介绍

Knife4j的前身是swagger-bootstrap-ui,前身swagger-bootstrap-ui是一个纯swagger-ui的ui皮肤项目

官网

地址

使用

第一步：在maven项目的pom.xml中引入Knife4j的依赖包，代码如下：

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-boot-starter</artifactId>
    <version>2.0.7</version>
</dependency>