如何用CLI设计高效易用的API接口

时间：2026-08-15 13:29

很多 API 设计教程都默认从鼠标操作开始：先打开可视化编辑器，把数据模型拖到画布上，再通过点击弹窗添加字段。这样的方式当然能完成 API 设计，但并不贴合许多研发团队真实的交付流程。如果你的接口定义托管在 Git 中，通过 Pull Request 评审，并最终进入 CI CD 流程，那么最理想的

很多 API 设计教程都默认从鼠标操作开始：先打开可视化编辑器，把数据模型拖到画布上，再通过点击弹窗添加字段。这样的方式当然能完成 API 设计，但并不贴合许多研发团队真实的交付流程。如果你的接口定义托管在 Git 中，通过 Pull Request 评审，并最终进入 CI/CD 流程，那么最理想的做法，通常是用与部署一致的方式来设计 API：在终端里、以文本形式、借助可脚本化执行的命令完成整个过程。

通过命令行设计 API，意味着你无需离开 shell，就能完成 API 契约编写、按风格指南进行 lint 校验、打包为单一文件，以及生成服务端桩代码。每一步都具备可重复执行的特点，每一步也都可以被纳入自动化流水线。当 AI Agent 或团队成员需要复现你的配置时，他们只要运行同样的命令即可，无需猜测你在图形界面里点过哪些按钮。

本指南会介绍两种常见路线。第一种是基于单一职责工具组合而成的通用开源方案：编写 OpenAPI 文件，使用 Spectral 做 lint 校验，使用 Redocly CLI 进行打包，再通过 openapi-generator 生成服务端桩代码。第二种是 Apifox CLI 路线，在这一方案中，API 设计、数据模型、接口定义和 auth 都统一保存在同一个项目里，可直接在终端中管理。如果你想先理解更底层的设计思路，建议结合阅读我们关于如何设计 API 的指南，以及 REST API 设计实战演练。

如果你准备跟随本文体验 Apifox，请先获取二进制文件。我们的 Apifox CLI 安装指南包含 npm install -g apifox-cli 的安装步骤，以及 apifox login --with-token 的认证流程；而完整的 Apifox CLI 指南则对每一个命令组都做了详细映射。

通用开源路线：编写、校验、打包、生成

经典的 CLI API 设计技术栈，通常由多款独立工具组合而成。你可以把接口定义保存在版本控制系统中的 OpenAPI 文件里，再把每个工具作为工作流中的一个独立步骤依次执行。这就是典型的 Git 原生 API 设计流程，也是很多团队偏爱的方式。下面来看它的具体实现。

编写 OpenAPI 文档

第一步通常是创建一个普通的 YAML 文件。你不需要依赖特殊编辑器，任何文本编辑器都可以完成。下面是一个最小化的 openapi.yaml 示例：

openapi: 3.0.3info:title: Orders APIversion: 1.0.0paths:/orders/{orderId}:get:operationId: getOrderparameters:- name: orderIdin: pathrequired: trueschema:type: stringresponses:'200':description: An ordercontent:application/json:schema:$ref: '#/components/schemas/Order'components:schemas:Order:type: objectrequired: [id, status]properties:id:type: stringstatus:type: stringenum: [pending, shipped, delivered]

当 API 文档规模逐渐扩大时，通常没有必要把所有定义都堆在一个文件里。更稳妥、也更适合团队协作的做法，是按模块拆分成多个文件，再使用 $ref 将它们串联起来。这样不仅数据模型更清晰，整体可读性也会更高，后续做代码评审、接口维护或多人协作时都会轻松很多。

使用 Spectral 进行 Lint 校验

手写 OpenAPI 规范时很容易出现不一致或遗漏。有人忘了填写 operationId，有人在响应定义中缺少文档描述，也有人临时发明了一套命名规则。API linter 可以在 Code Review 之前提前发现这类问题。Stoplight 推出的 Spectral 是非常主流的行业选择，它内置了 OpenAPI 规则集，同时也支持团队自定义规则。

npm install -g @stoplight/spectral-clispectral lint openapi.yaml

Spectral 会输出每个违规项对应的行号和严重级别。你还可以在 CI 中通过检查退出状态码，让构建在出现错误时自动失败。如果你在寻找替代方案，Redocly CLI 和 vacuum 同样可以完成 API lint 校验；其中 vacuum 速度非常快，也可以作为与 Spectral 兼容的校验工具使用。无论选择哪一种，本质上都一样：lint 校验是一个独立步骤，适合在 API 设计工作流中单独执行。

使用 Redocly CLI 打包

一旦你的 OpenAPI 定义被拆分为多个文件，大多数下游工具都会更偏好一个单一、自包含的文档。Redocly CLI 可以解析所有 $ref 引用，并将原本分层的结构打包、扁平化为一个文件。

npm install -g @redocly/cliredocly bundle openapi.yaml -o dist/openapi.bundled.yaml

除了 bundle 功能之外，Redocly 还支持 lint 校验（redocly lint）以及文档预览，因此有些团队会直接用它同时承担风格检查与打包工作。它的官方文档中也列出了完整的 CLI 命令集，适合进一步扩展使用。

使用 openapi-generator 生成桩代码

当你拿到一份干净且已经打包完成的 OpenAPI 规范后，就可以进入代码生成阶段。openapi-generator 能将 OpenAPI 文档转换成服务端桩代码、客户端 SDK 以及其他工程骨架，并支持数十种主流编程语言和框架。

npm install -g @openapitools/openapi-generator-cliopenapi-generator-cli generate -i dist/openapi.bundled.yaml -g spring -o ./server

你可以把 -g spring 替换成 -g python-flask、-g go-server，或任何其他支持的生成器。这样生成出来的项目脚手架就会与 API 契约保持一致，从而减少手工同步带来的偏差。

这就是一条完整的开源 API 设计路线：四个工具、四条命令，全部可脚本化、可自动化。它的成本在于需要你自己完成配置和衔接，包括文件组织方式、linter 规则、打包步骤以及代码生成器配置。每个工具都有自己的约定，因此会产生一定的粘合工作。如果你希望获得最高的可控性，并且不介意维护这些细节，这套方式会非常适合你。

Apifox CLI 路线：在单个项目中完成设计

另一种做法，是把 API 设计、数据模型、接口、mock 和 auth 统一保存在一个项目中，并通过终端直接驱动。apifox-cli 并不只是一个测试运行器，它更像是一个完整的项目资源管理 CLI。它提供覆盖设计全流程的命令组，包括用于数据模型的 schema、用于接口操作的 endpoint、用于组织管理的 folder、用于 auth 配置的 security-scheme，以及 import、export、mock 等能力。

需要先说明一点：Apifox 不负责执行 OpenAPI lint 校验，也不会帮你强制落实风格指南，这本来就不是它的定位。如果你的团队有 API 规范校验需求，仍然应该在流水线中保留 Spectral 或 vacuum。Apifox 也不是开源软件，而是一款提供免费额度的商业产品。它带来的价值，在于提供了一个一体化项目空间，让你无需手工拼接零散的设计资源。我们关于 API 设计与测试中 Swagger 替代方案的文章，也讨论了这种取舍在什么场景下更有意义。

首先安装并完成身份验证（请参考安装指南配置 Token）：

npm install -g apifox-cliapifox login --with-token

每条命令都会返回结构化 JSON，并且大多数响应里都带有一个 agentHints.nextSteps 字段，用于提示你或 AI Agent 下一步应该执行什么。在任意命令后追加 --help，即可查看完整参数说明。

使用 apifox schema 定义数据模型

API 设计通常从数据开始。一个可复用的 Order 数据模型，会成为接口引用时的唯一事实来源。这一点和原生 OpenAPI 中的 components/schemas 概念相同，只不过在这里它被当作项目资源来统一管理。

apifox schema --helpapifox schema create --project

由于命令输出是 JSON，你可以把结果通过管道传给 jq，提取新建数据模型的 ID，再传递给后续命令。如果你已经拥有现成的 OpenAPI 文件，也可以直接导入，而不需要重新手工录入所有 API 定义：

apifox import --project --file openapi.yaml

apifox import 支持 OpenAPI 3.x、Swagger 2.0、Postman 以及 Apifox 格式，因此你已有的接口定义通常只需一步，就能转化为一个可持续维护的活跃项目。

使用 apifox endpoint 定义接口

当数据模型准备好之后，就可以继续添加接口操作。endpoint 命令组用于创建和更新 API 接口，并把它们关联到你定义好的数据模型以及对应的目录结构中。

apifox endpoint --helpapifox endpoint list --project apifox endpoint create --project

以 JSON 形式列出接口本身就很有价值。你可以对比不同分支的输出结果做 diff，也可以把结果交给脚本处理，检查每个 path 是否都包含预期的响应定义。再结合 folder 命令对相关接口做分组，即使随着项目规模增长，整体结构依然能够保持清晰、易导航。

使用 apifox security-scheme 定义 auth

鉴权并不是上线前才补充的内容，而是 API 契约的一部分。security-scheme 命令组用于定义客户端的认证方式，例如 API Key、Bearer Token、OAuth 2.0 等。这些内容会映射到 OpenAPI 中的 components/securitySchemes，从而确保导入与导出过程能够平滑往返。

apifox security-scheme --helpapifox security-scheme list --project

在项目级别统一定义一次鉴权组件，意味着每个接口都可以复用它，而不必在每个操作上重复声明自己的 auth 规则。这种统一性，正是很多 API 校验工具希望你长期保持的设计规范。

使用 apifox cli-schema validate 校验您的写入

在提交修改或把项目接入 CI 之前，你需要先确认资源定义本身的格式没有问题。CLI 提供了 cli-schema validate 命令，可以依据 CLI 所期望的数据结构来校验定义文件，从而让格式错误尽早暴露，而不是在后台悄悄失败。

apifox cli-schema --helpapifox cli-schema validate --file resource.json

建议在流水线中把它作为一个守卫步骤：先校验，再应用。只要返回非零退出状态码，就可以在错误资源写入项目之前中止流程。需要特别区分的是，这一步校验的是 CLI 资源结构，而不是 OpenAPI 风格检查；如果你要做 API linting，仍然应当使用 Spectral。

导出回 OpenAPI

你完全可以在 Apifox 中完成 API 设计，再把标准化产物交给后续工具链继续处理。apifox export 支持导出 OpenAPI、HTML、Markdown 或 Postman 格式文件。

apifox export --project --format openapi -o dist/openapi.yaml

完成这一步后，你手中就会得到一份可移植的 OpenAPI 文件。接下来它的用途非常灵活：可以交给 Spectral 做风格检查，可以交给 openapi-generator 生成桩代码，也可以直接接入 API 文档生成流程。从这个角度看，一体化项目与开放式工具链并不是互相排斥的选择，而这次导出正是打通两者的关键环节。

接入 CI

无论采用哪一种方案，它们都非常适合纳入 CI/CD 流水线，因为每条命令都提供明确的退出状态码和文本输出。一个最小可用的 API 设计检查任务，通常可以依次执行 linter 检查、资源校验，然后再进行打包：

# fail on style violationsspectral lint openapi.yaml# validate any CLI resource writes before applyingapifox cli-schema validate --file resource.json# flatten to a single artifact for downstream stepsredocly bundle openapi.yaml -o dist/openapi.bundled.yaml

由于 Apifox 输出的是包含 agentHints.nextSteps 的结构化 JSON，这种流程也非常适合由 AI 编码 Agent 驱动。Agent 只需读取结构化结果，获取建议的下一步操作并直接执行，而不需要通过截图识别 GUI。说到底，这正是采用 CLI 设计 API 的初衷：人类能输入的命令，脚本和 Agent 同样也能稳定执行。

常见问题

拆分文件会破坏下游工具。对于人工阅读来说，把定义分散在多个 $ref 文件中非常友好；但对生成器或文档工具来说，这往往会增加处理难度。因此在生成代码或发布文档之前，请务必先将其打包（bundle）成单个文件。使用 redocly bundle 就能解决这个问题。

期望 Apifox 执行风格检查，但它并不会。 Apifox 的职责是管理项目资源，而不是执行 OpenAPI 风格规范校验。它不会自动强制风格指南，也不会提示 OpenAPI 规则违规。相关工作仍应交给 Spectral 或 vacuum。很多人会把 apifox cli-schema validate 误解为 linter，但它检查的是资源结构，不是 API 风格。

在编辑前忘记导入。如果你打算通过 CLI 维护一个已有 API，请先把源定义导入到项目中。若直接在空项目上编辑，却期待原本的接口自动存在，往往会让整个过程变得混乱。

在每个接口上单独定义 auth，而不是统一配置。更推荐在项目级别定义 security-scheme（鉴权组件）并由各接口统一引用。把 auth 重复写在每个操作上，往往正是导致 API 契约逐渐偏离的根源之一。

总结

通过 CLI 设计 API，本质上是把分散、难复现的点击操作，转化为一套稳定、可重复、可自动化执行的命令链路。开放工具路线——编写 OpenAPI、使用 Spectral 做 lint 校验、使用 Redocly 打包、使用 openapi-generator 生成代码——能够提供最大的控制权，同时避免厂商锁定。而 Apifox CLI 路线则提供了一个集成式项目空间，让数据模型、接口与 auth 在同一处协同管理，并且每条命令都返回适合 Agent 消费的 JSON。导出能力则成为连接这两种方案的桥梁，让你始终保有灵活性。

选择最适合团队协作方式的路线。如果你的团队已经习惯 Git 驱动和多工具组合的 API 设计流程，那就继续沿用这套方式，并在需要可移植产物时结合 apifox export。如果你不想长期维护这些工具之间的粘合层，那么可以直接下载 Apifox，安装 CLI，然后在不依赖鼠标的前提下完成下一个 API 的设计与管理。