springboot整合swagger，postman,接口规范

一、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>io.springfox</groupId>
            <artifactId>springfox-boot-starter</artifactId>
            <version>3.0.0</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/"));
    }
}

启动测试

三、idea内部测试工具