当前位置：首页 > news >正文

springboot整合swagger，postman,接口规范

news 2025/9/10 20:57:13

一、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语义。

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  // 创建一个Beanpublic GroupedOpenApi FileApi() {// 创建一个GroupedOpenApi对象，设置其组名为"支付微服务模块"，并匹配所有以"/file/"开头的路径return GroupedOpenApi.builder().group("支付微服务模块").pathsToMatch("/file/**").build();}@Bean  // 创建一个Beanpublic GroupedOpenApi OtherApi() {// 创建一个GroupedOpenApi对象，设置其组名为"其它微服务模块"，并匹配所有以"/other/"开头或等于"/others"的路径return GroupedOpenApi.builder().group("其它微服务模块").pathsToMatch("/other/**", "/others").build();}@Bean  // 创建一个Beanpublic 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/"));}
}