springboot整合swagger，postman,接口规范

青旅半醒 2024-04-17 13:47 59阅读 0赞

## 一、postman介绍 ##

### 1.1概述 ###

> #### 工具下载 ####
> 
> Postman（发送 http 请求的工具）  
> 官网（下载速度比较慢）：[Download Postman | Get Started for Free][Download Postman _ Get Started for Free]  
> 网盘下载：[百度网盘 请输入提取码][Link 1]

### 1.2Http 请求格式 ###

![e81c002ee01a4c90aa6e94e065e75042.png][]

*  **请求地址**
 *  **请求方法**
 *  **状态码**
 *  **同源策略**
 *  **请求头**
 *  **响应头**

### 1.3接口类型 ###

#### Post 接口（新增数据） ####

@RequestMapping(method = RequestMethod.POST)
    @PostMapping("/post")

## ![3ab1fc4ba0434be686b0498b6afb3e1c.png][] ##

如果你这样写，是 url 参数，并且 url 参数可以为空

@PostMapping("/post")     // http://localhost:9090/web/post?name=青哥哥&age=30
    public Result post(Obj obj) {
        return Result.success(obj);
    }

##### 怎么请求 json 数据？ #####

![84f0403a4ffe4f5880600c6d516ae445.png][]

#### Put 接口（更新数据） ####

@RequestMapping(method = RequestMethod.PUT)
    @PutMapping("/put")

## ![6f5db7a267344f7aaee9650b463cd2f5.png][] ##

#### Delete 接口（删除数据） ####

@RequestMapping(method = RequestMethod.DELETE)
    @DeleteMapping("/delete/{id}")

## ![eebaee4a9aa847b387bc5a57fc21b905.png][] ##

##### delete 可以传 json 数据 #####

我们批量删除可以使用 delete 类型的接口

![39d44c8e054848a9aef80e256d11d1a0.png][]

#### Get 接口 ####

@RequestMapping()
    或者
    @GetMapping("/hello")

怎么定义路由

![26eff1207a0e4cae992e01c7fd2eb833.png][]

## 1.4Http 状态码 ##

下述做常见的基本介绍，详细请看[有趣的小知识（一）HTTP请求响应状态码：一份不可或缺的指南，从容面对任何请求挑战！][HTTP]

*  **200：成功**
 *  **400：接口参数错误**

![image.png][]

*  **404：接口路径写错了或者参数写错了**![28dde9cbbec14448a2a56b7ecd6abdb5.png][]

*  **405：接口请求类型不匹配**
 *  ![image.png][image.png 1]

![image.png][image.png 2]

![image.png][image.png 3]

*  **500：后台错误**

###  ###

![image.png][image.png 4]

当你的请求出现**500 错误**的时候，你应该怎么办？  
第一时间，赶紧去看下后台的控制台

## ![1a78070f3b144aa8888ba11c01fc358e.png][]二、swagger ##

### 2.1文档规范概述 ###

![aa965724e0194104bfd22b9779689aa6.png][]

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

![0b47795d1d2742ba85da5ac65486412c.png][]

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

#### 相关依赖 ####

<dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-boot-starter</artifactId>
        <version>3.0.0</version>
    </dependency>

#### 相关注解 ####

![e4ee63f116ee4f9996d1b38615fd3de1.png][]

## 2.4使用 ##

#### 依赖 ####

<dependency>
                <groupId>org.springdoc</groupId>
                <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
                <version>2.0.2</version>
            </dependency>

#### 常用注解 ####

![48c3fc72b72a4839bb41aa10f108f784.png][]

@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/"));
        }
    }

#### 启动测试 ####

## 三、idea内部测试工具 ##

![7683c798568d411396a855fbf8247db2.png][]

![04207ede8f7449e0911c4ba734ce6980.png][]

####  ####

[Download Postman _ Get Started for Free]: https://www.postman.com/downloads/
[Link 1]: https://pan.baidu.com/s/1_a54AxH2rZr0bhSlroIBRw?pwd=5y5u
[e81c002ee01a4c90aa6e94e065e75042.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/04/13/ae341bdd810b4ccab1c4a8b5b1fd2e82.png
[3ab1fc4ba0434be686b0498b6afb3e1c.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/04/13/f74d4c915f3d456c903b787406d61ac4.png
[84f0403a4ffe4f5880600c6d516ae445.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/04/13/54ceacfb0855439e8d0c4246e0813ec5.png
[6f5db7a267344f7aaee9650b463cd2f5.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/04/13/544c63c5dcc34a329c28ffa5b5604ed7.png
[eebaee4a9aa847b387bc5a57fc21b905.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/04/13/0765a4505b6840bab510465d96c2081f.png
[39d44c8e054848a9aef80e256d11d1a0.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/04/13/153ecbe049ec48fe9c01e1c4950abc14.png
[26eff1207a0e4cae992e01c7fd2eb833.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/04/13/db71a766ebe8481a8f481ec261c22d9b.png
[HTTP]: https://blog.csdn.net/qq_62377885/article/details/129259318
[image.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/04/13/01eb857199434179adff4b81afcd22a8.png
[28dde9cbbec14448a2a56b7ecd6abdb5.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/04/13/0e0f0e9d7fb8459f87da3be7d87881d2.png
[image.png 1]: https://image.dandelioncloud.cn/pgy_files/images/2024/04/13/0311e74b2e63410bbf01fc4b05f45977.png
[image.png 2]: https://image.dandelioncloud.cn/pgy_files/images/2024/04/13/e0c8af333d0140c884c741b35ac75555.png
[image.png 3]: https://image.dandelioncloud.cn/pgy_files/images/2024/04/13/e94b5dd3fb8342afadd8aa15a4817f26.png
[image.png 4]: https://image.dandelioncloud.cn/pgy_files/images/2024/04/13/87cf43d791ea409bbe3e9208d8d5ec2b.png
[1a78070f3b144aa8888ba11c01fc358e.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/04/13/ba1d98b86dd64ab0ae787d8d5781e88d.png
[aa965724e0194104bfd22b9779689aa6.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/04/13/03f37534a7984346b2511db4a8f20d6c.png
[0b47795d1d2742ba85da5ac65486412c.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/04/13/a8b9fb91787a44b8b7f6c92fc609d398.png
[e4ee63f116ee4f9996d1b38615fd3de1.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/04/13/34974ccd57d94987adbf67d3abba188d.png
[48c3fc72b72a4839bb41aa10f108f784.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/04/13/84504ec6a98345cb977b348bd05ec9db.png
[7683c798568d411396a855fbf8247db2.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/04/13/480365b53c594ae9979b973d7951f370.png
[04207ede8f7449e0911c4ba734ce6980.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/04/13/48900768165a433581606cbbe333ef46.png