【前后端】接口文档与导入

文章目录

前言
[定义概念 + 缩写](#定义概念 + 缩写)
- - [**API --- Application Programming Interface**](#API — Application Programming Interface)
  - **Swagger（OpenAPI）**
  - **YAPI**
  - **Mock**
  - **Sync（自动同步）**
性质
使用步骤（核心）
- [① 后端生成 Swagger 文档](#① 后端生成 Swagger 文档)
- - [SpringBoot 中引入依赖（示例）](#SpringBoot 中引入依赖（示例）)
  - [访问 Swagger JSON 地址](#访问 Swagger JSON 地址)
- [② 导入到 YAPI（平台端）](#② 导入到 YAPI（平台端）)
- - 步骤
- [③ 前端使用 Mock 数据自测](#③ 前端使用 Mock 数据自测)
- [④ 后端更新接口 → YAPI 自动同步](#④ 后端更新接口 → YAPI 自动同步)
示例代码
- [Python 调用 YAPI Mock](#Python 调用 YAPI Mock)
- [Matlab 调用 HTTP 接口](#Matlab 调用 HTTP 接口)
- [C 语言调用接口（libcurl）](#C 语言调用接口（libcurl）)
总结
参考文献

前言

在前后端分离开发模式中，接口文档的规范化管理 是协作效率的核心。

无论使用 YAPI、Apifox、Swagger、Postman，接口文档的导入与同步都是最基础、也是最容易被忽视的部分。

本文精简介绍：

接口文档为什么要导入
常见的接口文档格式
如何将接口一键导入到 YAPI / Apifox / Swagger
实际项目中的最佳实践

定义概念 + 缩写

API --- Application Programming Interface

后端对外暴露的接口规范（URL、方法、参数、返回值）。

Swagger（OpenAPI）

最底层、行业标准的接口定义格式（JSON / YAML）。

YAPI

团队使用广泛的 接口管理平台，支持 Swagger 导入。

Mock

根据接口文档自动生成模拟数据，供前端自测。

Sync（自动同步）

后端更新 Swagger → 前端/YAPI 自动同步。

性质

特性	说明
标准化	Swagger 是业界标准，99% 平台兼容
可视化	自动生成接口列表、参数说明、示例响应
Mock 支持	文档即可生成 Mock 数据（前端可立即开发）
自动同步	后端改接口 → 前端实时获取最新结构
测试支撑	多平台可直接调用、调试、校验格式

使用步骤（核心）

下面以 SpringBoot + Swagger3 + YAPI 为主线，演示完整流程。

① 后端生成 Swagger 文档

SpringBoot 中引入依赖（示例）

xml 复制代码

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

访问 Swagger JSON 地址

复制代码

http://localhost:8080/v3/api-docs

这个 JSON 就是可导入 YAPI / Apifox 的核心文件。

② 导入到 YAPI（平台端）

步骤

登录 YAPI
创建项目（或选择已有项目）
左侧选择 接口管理 → 数据管理
选择 Swagger 导入
填写接口 URL，例如：

http://localhost:8080/v3/api-docs
点击导入 → 自动生成目录、接口、字段类型、返回结构

YAPI 会自动解析所有 Controller → 自动生成 API 文档。

③ 前端使用 Mock 数据自测

YAPI 每个接口都有 Mock 地址，例如：

复制代码

http://yapi.xxx/mock/123/api/login

前端在未连上后端之前即可运行完整流程（登录、下单、列表、分页）。

④ 后端更新接口 → YAPI 自动同步

后端更新接口文档（新增字段、修改 DTO），YAPI 可以：

手动同步
定时自动同步
提示差异（新增、删除、变更字段）

让"前后端对齐接口格式"成为自动化流程。

示例代码

Python 调用 YAPI Mock

py 复制代码

import requests

resp = requests.get("http://yapi.xxx/mock/123/api/user")
print(resp.json())

Matlab 调用 HTTP 接口

matlab 复制代码

url = 'http://yapi.xxx/mock/123/api/user';
data = webread(url)

C 语言调用接口（libcurl）

c 复制代码

CURL *curl = curl_easy_init();
if(curl) {
    curl_easy_setopt(curl, CURLOPT_URL, "http://yapi.xxx/mock/123/api/user");
    curl_easy_perform(curl);
    curl_easy_cleanup(curl);
}

总结

前后端分离必须依赖接口文档平台，统一输入、输出、状态码、Mock。
Swagger 是底层协议，YAPI / Apifox 是上层管理工具。
在后端生成 Swagger → 导入到 YAPI → 前端基于文档开发 → 联调 → 自动化测试，这是标准流程。
良好的接口文档能显著降低团队沟通成本，提高联调效率，减少 Bug。

参考文献

$1$ Swagger 官方文档 --- https://swagger.io

$2$ YAPI 官方文档

$3$ SpringFox API 包文档