Swagger及knife4j的基本使用详解
作者:ProsperousEnding 发布时间:2023-02-13 09:34:00
Swagger以及knife4j基本使用
Swagger 介绍:
官网:https://swagger.io/
Swagger是一个规范和完整的框架,用于生成、描述、调用和可视化RESTful风格的 Web 服务
Restful 面向资源
RESTful是一种架构的规范与约束、原则,符合这种规范的架构就是RESTful架构
Rest是web服务的一种架构风格;使用HTTP,URI,XML,JSON,HTML等广泛流行的标准和协议;轻量级,跨平台,跨语言的架构设计,它是一种设计风格,不是一种标准,是一种思想。
说明:
http方法 | 资源操作 | 幂等 | 安全 |
---|---|---|---|
GET | SELECT | 是 | 是 |
POST | INSERT | 否 | 否 |
PUT | UPDATE | 是 | 否 |
DELETE | DELETE | 是 | 否 |
幂等性:对同一REST接口多次访问,得到的资源状态是相同的
安全性:对该REST接口访问,不会使服务端资源状态发生改变
优点:
透明性 --暴露资源存在(资源操作通过http本身语义进行描述,不用单独描述)
充分利用HTTP协议本身语义
无状态 --在调用一个接口时可以不用考虑上下文,不用考虑当前状态降低了复杂度
HTTP本身提供了丰富的内容协商手段(缓存,资源修改的乐观并发控制等可以通过与业务无关的中间件实现)
SpringBoot使用swagger
导入依赖
2版本
<!--swagger依赖-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<!--swagger ui-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
3.0版本
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-boot-starter</artifactId>
<version>3.0.0</version>
</dependency>
2.编写swagger配置文件
@Configuration
@EnableSwagger2 //开启Swagger2
public class Swagger2Config {
/**
* 创建API应用
* apiInfo() 增加API相关信息
* 通过select()函数返回一个ApiSelectorBuilder实例,用来控制哪些接口暴露给Swagger来展现,
* 指定扫描的包路径来定义指定要建立API的目录。
* @return
*/
@Bean
public Docket docket(){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(adminApiInfo())
//.enable(false) //enable是否启动Swagger 如果为false,则swagger不能在浏览器中访问
.groupName("adminApi")
.select()
//RequestHandlerSelectors 配置要扫描接口的方式
//basePackage: 指定要扫描的包
//any():扫描全部
//none()不扫描
//withClassAnnotation: 扫描类上的注解,参数为一个注解的反射对象
//withMethodeAnnotation: 扫描方法上的注解
.apis(RequestHandlerSelectors.basePackage("com.example.swagger.controller"))
//只显示admin下面的路径
.paths(Predicates.and(PathSelectors.regex("/admin/.*")))
.build();
}
private ApiInfo adminApiInfo(){
return new ApiInfoBuilder()
.title("api文档")
.description("系统接口描述")
.version("1.0")
//作者信息
.contact(new Contact("张三","http://baidu.com","12345678@qq.com"))
.build();
}
}
3.编写接口请求并运行
访问方式(本地):http://localhost:8080/swagger-ui.html
使用:
实体类:
@ApiModel("用户实体类")
public class User{
@ApiModelProperty("用户名")
public String username;
}
接口方法,参数:
@RestController
public class UserController{
@ApiOperation("User控制类")
@GetMapping(value="/user")
public String getUser(@ApiParam("用户名")String username){
return "名字为:"+username;
}
}
常用注解:
@Api:修饰整个类,描述Controller的作用,放在类上
@ApiOperation:描述一个类的一个方法,或者说一个接口
@ApiParam:单个参数描述
@ApiModel:用对象来接收参数
@ApiProperty:用对象接收参数时,描述对象的一个字段
@ApiResponses:HTTP响应整体描述
@ApiResponse:HTTP响应其中1个描述
@ApiIgnore:使用该注解忽略这个API
@ApiError :发生错误返回的信息
@ApiImplicitParams:描述由多个 @ApiImplicitParam 注解的参数组成的请求参数列表
@ApiImplicitParam:描述一个请求参数,可以配置参数的中文含义,还可以给参数设置默认值
//eg:
@ApiImplicitParam(name="username",value="用户名",required=true)
Knife4j --Swagger增强工具
使用Knife4j2.06以上版本,springboot版本必须大于等于2.2.x
作用
可以搜索接口名称快速定位接口(搜索功能)
可以下载markdown、HTML、word 等格式文件(下载功能)
1.引入依赖
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-spring-boot-starter</artifactId>
<version>2.0.9</version>
</dependency>
2.添加SwaggerConfiguration作为Swagger2的配置类
@Configuration
@EnableSwagger2
@EnableKnife4j
//@EnableSwagger2WebMvc 2.6以上报空指针异常则需要添加
@Import(BeanValidatorPluginsConfiguration.class)
public class SwaggerConfiguration {
@Bean
public Docket api() {
return new Docket(DocumentationType.SWAGGER_2) // 选择swagger2版本
.apiInfo(apiInfo()) //定义api文档汇总信息
.select()
.apis(RequestHandlerSelectors
.basePackage("com.example")) // 指定生成api文档的包
.paths(PathSelectors.any()) // 指定所有路径
.build();
}
/**
* 构建文档api信息
*
* @return
*/
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("") // 文档标题
.contact(new Contact("", "", "")) //联系人信息
.description("") //描述
.version("1.0.1") //文档版本号
.termsOfServiceUrl("") //网站地址
.build();
}
}
3.实现生产环境关闭文档资源
spring:
profiles: prod #指定环境
knife4j:
production: true #开启屏蔽文档资源
4.实现接口排序
针对不同Controller排序:Controller上标注
@ApiSupport(order = 序号)
针对同一个Controller中的不同方法排序:同一个Controller不同接口方法上标注
@ApiOperationSupport(order = 序号)
注:更多详细配置:swagger文档增强工具knife4j使用详解
来源:https://www.cnblogs.com/prosperous-ending-0925/archive/2022/08/22/16612462.html
猜你喜欢
- 很多学习Android程序设计的人都会发现每个人对代码的写法都有不同的偏好,比较明显的就是对控件响应事件的写法的不同。因此本文就把这些写法总
- 了解JVM内存结构的目的在Java的开发过程中,因为有JVM自动内存管理机制,不再需要像在C、C++开发那样手动释放对象的内存空间,不容易出
- 在logback.xml中加上该配置,包名如:com.xxx<logger name="packageName"
- 1. 继承1. 子类继承了父类,获得父类的全部Field和方法。子类Student类继承父类,将可以获得父类的全部Field和方法publi
- 引言我已经一个多星期没碰过电脑了,今日上班,打开电脑的第一件事就是想着写点什么。反正大家都还沉浸在节后的喜悦中,还没进入工作状态,与其浪费时
- 本文实例为大家分享了java中文传值乱码问题,以及解决方法,供大家参考,具体内容如下一般编码格式设置:1.可以经过两次编码处理,即设置字符集
- @GetMapping和@GetMapping(value=““)区别背景初期对于@GetMappi
- 前情提要我们上节内容学习了如何创建\注册\读取bean我们发现bean对象操作十分的繁琐!所以我们这个章节,就带大家来了解更加简单的bean
- 一、分步骤集成1.1 整合连接池hikariCP介绍:HikariCP 是一个高性能的 JDBC 连接池组件,可以避免连接频繁建立、关闭的开
- 实例如下:import java.lang.reflect.Field;import java.lang.reflect.Invocatio
- 近日于LeetCode看题遇1114 按序打印,获悉一解法使用了Semaphore,顺势研究,记心得于此。此解视Semaphore为锁,以保
- yml 文件规则yml文件的好处,天然的树状结构,一目了然,实质上跟properties是差不多的。不支持tab缩进可以使用 "-
- Spring boot默认使用的是SimpleCacheConfiguration,即使用ConcurrentMapCacheManager
- 简介本文用示例介绍使用MyBatis-Plus进行多表查询的方法,包括静态查询和动态查询。代码controllerpackage com.e
- 二分查找又称折半查找,它是一种效率较高的查找方法。折半查找的算法思想是将数列按有序化(递增或递减)排列,查找过程中采用跳跃式方式查找,即先以
- 封面图下个季度的目标是把前端监控相关的内容梳理出来,梳理出来之后可能会在公司内部做个分享~Flutter应用程序既括代码也包括一些其他的资产
- 本文介绍了Flutter 通过Clipper实现各种自定义形状的示例代码,分享给大家,具体如下:ClipOval 圆形裁剪ClipOval(
- SpringMvc中普通类注入Service为null场景:使用Quartz定时器时,普通的java类需要注入spring的service类
- 最近项目中需要实现定时执行任务,比如定时计算会员的积分、调用第三方接口等,由于项目采用spring框架,所以这里结合spring框架来介绍。
- 在spring中有很多以XXXAware命名的接口,很多人也不清楚这些接口都是做什么用的,这篇文章将描述常用的一些接口。一,Applicat