一、postman介绍
1.1概述
工具下载
Postman(发送 http 请求的工具)
官网(下载速度比较慢):Download Postman | Get Started for Free
网盘下载:百度网盘 请输入提取码
1.2Http 请求格式
- 请求地址
- 请求方法
- 状态码
- 同源策略
- 请求头
- 响应头
1.3接口类型
Post 接口(新增数据)
@RequestMapping(method = RequestMethod.POST)
@PostMapping("/post")
如果你这样写,是 url 参数,并且 url 参数可以为空
@PostMapping("/post") // http://localhost:9090/web/post?name=青哥哥&age=30
public Result post(Obj obj) {
return Result.success(obj);
}
怎么请求 json 数据?
Put 接口(更新数据)
@RequestMapping(method = RequestMethod.PUT)
@PutMapping("/put")
Delete 接口(删除数据)
@RequestMapping(method = RequestMethod.DELETE)
@DeleteMapping("/delete/{id}")
delete 可以传 json 数据
我们批量删除可以使用 delete 类型的接口
Get 接口
@RequestMapping()
或者
@GetMapping("/hello")
怎么定义路由
1.4Http 状态码
下述做常见的基本介绍,详细请看有趣的小知识(一)HTTP请求响应状态码:一份不可或缺的指南,从容面对任何请求挑战!
- 200:成功
- 400:接口参数错误
- 404:接口路径写错了或者参数写错了
- 405:接口请求类型不匹配
-
- 500:后台错误
当你的请求出现500 错误的时候,你应该怎么办?
第一时间,赶紧去看下后台的控制台
二、swagger
2.1文档规范概述
OpenAPI规范(OpenAPI Specification简称OAS)是Linux基金会的一个项目,OpenAPI规范是用于描述API的行业标准,它允许开发人员在不阅读源代码或文档的情况下就能理解API的功能;通过JSON格式描述
2.2API文档神器Swagger介绍
Swagger是目前最受欢迎的基于OpenAPI规范的开源API构建工具;
官网:https:/swagger.io/
作用:在代码中添加注解即可生成AP接口文档;
<dependency>
<groupId>io.swagger.core.v3</groupId>
<artifactId>swagger-annotations</artifactId>
<version>2.2.20</version>
</dependency>
Swagger 是一套基于 OpenAPI 规范(OpenAPI Specification,OAS)构建的开源工具,可以帮助我们设计、构建、记录以及使用 REST API。
OpenAPI规范是在2015年由OpenAPI Initiative捐赠给Linux基金会的。该规范创建了RESTful接口,可通过有效映射与之关联的所有资源和操作来轻松开发和使用API。
Swagger 主要包含了以下三个部分:
- Swagger Editor:基于浏览器的编辑器,我们可以使用它编写我们 OpenAPI 规范。
- Swagger UI:它会将我们编写的 OpenAPI 规范呈现为交互式的 API 文档,后文我将使用浏览器来查看并且操作我们的 Rest API。
- Swagger Codegen:它可以通过为 OpenAPI(以前称为 Swagger)规范定义的任何 API 生成服务器存根和客户端 SDK 来简化构建过程。
2.3SpringFox
Springfox的Java库套件旨在自动生成使用spring系列项目编写的JSON API的机器和人类可读规范。
Springfox的工作原理是在运行时检查应用程序,以基于Spring配置,类结构和各种编译时Java注释来推断API语义。
相关依赖
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-boot-starter -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-boot-starter</artifactId>
<version>3.0.0</version>
</dependency>
相关注解
2.4使用
依赖
<dependency>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
<version>2.0.2</version>
</dependency>
常用注解
@Tag(name = "文件上传下载" ,description = "文件上传下载接口")
public String File() {
return "file_upload_download";
}
@GetMapping("/download/{fileName}")
@Operation(summary = "文件下载",description = "文件下载接口")
public Result download(@PathVariable("fileName") String fileName, HttpServletResponse response) throws IOException {
String filePath = ROOT_PATH + File.separator + fileName;
if (!FileUtil.exist(filePath)) {
return Result.error("文件不存在");
}
// response.addHeader("Content-Disposition", "inline;filename=" + URLEncoder.encode(fileName, "UTF-8")); // 预览
byte[] bytes = FileUtil.readBytes(filePath);
ServletOutputStream outputStream = response.getOutputStream();
outputStream.write(bytes); // 数组是一个字节数组,也就是文件的字节流数组
outputStream.flush();
outputStream.close();
System.out.println("文件下载成功");
return Result.success();
}
@Schema(description = "返回结果")
public class Result {
public static final String CODE_SUCCESS = "200";
public static final String CODE_AUTH_ERROR = "401";
public static final String CODE_SYS_ERROR = "500";
@Schema(description = "状态码")
private String code;
@Schema(description = "消息")
private String msg;
@Schema(description = "数据")
private Object data;
配置类
package com.yanyu.upload3.Config;
import io.swagger.v3.oas.models.ExternalDocumentation;
import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Info;
import org.springdoc.core.GroupedOpenApi;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
@Configuration // 表示这是一个配置类
public class Swagger3Config1 {
@Bean // 创建一个Bean
public GroupedOpenApi FileApi() {
// 创建一个GroupedOpenApi对象,设置其组名为"支付微服务模块",并匹配所有以"/file/"开头的路径
return GroupedOpenApi.builder().group("支付微服务模块").pathsToMatch("/file/**").build();
}
@Bean // 创建一个Bean
public GroupedOpenApi OtherApi() {
// 创建一个GroupedOpenApi对象,设置其组名为"其它微服务模块",并匹配所有以"/other/"开头或等于"/others"的路径
return GroupedOpenApi.builder().group("其它微服务模块").pathsToMatch("/other/**", "/others").build();
}
@Bean // 创建一个Bean
public OpenAPI docsOpenApi() {
// 创建一个OpenAPI对象,设置其标题为"cloud2024",描述为"通用设计rest",版本为"v1.0"
// 并设置其外部文档的描述为"www.yanyu.com",URL为"https://yanyu.com/"
return new OpenAPI()
.info(new Info().title("upload3")
.description("通用设计rest")
.version("v3.0"))
.externalDocs(new ExternalDocumentation()
.description("www.yanyu.com")
.url("\"https://yanyu.com/"));
}
}