Swagger及knife4j的基本使用详解
Swagger以及knife4j基本使用
Swagger 介绍:
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使用详解
到此这篇关于Swagger以及knife4j的基本使用的文章就介绍到这了,更多相关Swagger knife4j使用内容请搜索脚本之家以前的文章或继续浏览下面的相关文章希望大家以后多多支持脚本之家!
相关文章
使用springmvc的controller层获取到请求的数据方式
这篇文章主要介绍了使用springmvc的controller层获取到请求的数据方式,具有很好的参考价值,希望对大家有所帮助。如有错误或未考虑完全的地方,望不吝赐教2021-08-08SpringBoot项目Maven下载依赖速度慢问题的解决方法
在使用Maven构建项目时,有时会遇到下载依赖包速度慢的问题,为了提高下载速度,我们可以将默认的仓库地址替换为国内镜像源,所以本文介绍了SpringBoot项目Maven下载依赖速度慢问题的解决方法,需要的朋友可以参考下2024-08-08使用java -jar修改SpringBoot中application.properties的配置项
这篇文章主要介绍了使用java -jar修改SpringBoot中application.properties的配置项问题,具有很好的参考价值,希望对大家有所帮助。如有错误或未考虑完全的地方,望不吝赐教2023-02-02Spring Boot 2.X整合Spring-cache(让你的网站速度飞起来)
这篇文章主要介绍了Spring Boot 2.X整合Spring-cache(让你的网站速度飞起来),文中通过示例代码介绍的非常详细,对大家的学习或者工作具有一定的参考学习价值,需要的朋友们下面随着小编来一起学习学习吧2019-09-09IDEA打开java项目后里面的java文件不能运行解决办法
这篇文章主要给大家介绍了关于IDEA打开java项目后里面的java文件不能运行的解决办法,有时候想运行别人的项目,但是别人的项目并非IDEA项目(甚至只有源码),当我们打开项目时候,并不能运行,需要的朋友可以参考下2023-10-10
最新评论