如何通过 CLI 设计 API

大多数 API 设计教程都是从使用鼠标开始的。打开可视化编辑器，将数据模型拖到画布上，然后点击对话框来添加字段。这种方式虽然可行，但不符合许多团队的实际交付流程。如果您的接口定义托管在 Git 中，通过拉取请求（pull request）进行评审，并流经 CI，那么您一定会希望以部署它的方式来进行设计：在终端中，以文本形式，使用可以通过脚本运行的命令。

从命令行设计 API 意味着您可以在不离开 shell 的情况下，编写契约、根据风格指南对其进行 lint 校验、将其打包为单个文件并生成桩代码。每一个步骤都是可重复的。每一个步骤都可以在流水线中运行。当 AI Agent 或团队成员需要复现您的配置时，他们只需运行您执行过的相同命令，而无需猜测您点击了哪些按钮。

本指南将介绍两条路线。首先是基于单一功能工具构建的通用开源路径：编写 OpenAPI 文件，使用 Spectral 对其进行 lint 校验，使用 Redocly CLI 将其打包，然后使用 openapi-generator 生成服务端桩代码。接着是 Apifox CLI 路径，在该路径下，设计、数据模型、接口和 auth 都集中在一个项目中，您可以直接在终端中进行操作。如果您想先了解更深层次的概念背景，请阅读我们关于如何设计 API 的指南以及设计 REST API 的演练。

如果您要跟随本文使用 Apifox，请先获取二进制文件。我们的 Apifox CLI 安装指南介绍了 npm install -g apifox-cli 步骤和 apifox login --with-token 握手，并且完整的 Apifox CLI 指南映射了每个命令组。

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

经典的 CLI 设计技术栈是一套由您组合在一起的独立工具。您将接口定义保存在版本控制下的 OpenAPI 文件中，并将每个工具作为其中的一个步骤运行。这就是 Git 原生的 API 设计工作流，它确实非常优秀。以下是它的具体流程。

编写 OpenAPI 文档

您首先需要创建一个普通的 YAML 文件。不需要特殊的编辑器，任何文本编辑器都可以。一个最小的 openapi.yaml 示例如下：

openapi: 3.0.3
info:
  title: Orders API
  version: 1.0.0
paths:
  /orders/{orderId}:
    get:
      operationId: getOrder
      parameters:
        - name: orderId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: An order
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
components:
  schemas:
    Order:
      type: object
      required: [id, status]
      properties:
        id:
          type: string
        status:
          type: string
          enum: [pending, shipped, delivered]

随着 API 的增长，您可以将其拆分到多个文件中，并通过 $ref 进行引用。这样可以保持每个数据模型的可读性，并便于独立进行评审。

使用 Spectral 进行 Lint 校验

手写的 OpenAPI 规范容易发生偏差。有人漏掉了 operationId，另一个人在编写响应时未提供文档，还有人自创了命名规范。校验器（linter）可以在 Code Review 之前捕获所有这些问题。Stoplight 旗下的 Spectral 是行业标准选择。它内置了针对 OpenAPI 的规则集，并允许你编写自定义规则。

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

Spectral 会打印出每个违规项所在的行号和严重程度。你可以通过在 CI 中检查退出状态码，从而在出现错误时使构建失败。如果你想寻找替代方案，Redocly CLI 和 vacuum 也能完成同样的工作；vacuum 速度极快，可以作为与 Spectral 兼容的校验器直接使用。无论你选择哪一个，其本质都一样：lint 校验是一个独立的专用工具，你需要将其作为一个单独的步骤运行。

使用 Redocly CLI 打包

一旦你的定义被拆分到多个文件中，大多数下游工具都会需要一个单一且自包含的文档。Redocly CLI 会解析每个 $ref 并将树状结构扁平化为一个文件。

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

Redocly 还支持 lint 校验（redocly lint）和预览文档，因此一些团队用它来同时进行风格检查和打包。它的官方文档中列出了完整的命令集。

使用 openapi-generator 生成桩代码

拥有干净、打包后的规范后，你就可以生成代码了。openapi-generator 可以将 OpenAPI 文档转换为服务端桩代码、客户端 SDK 等，支持数十种编程语言。

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

将 -g spring 替换为 -g python-flask、-g go-server 或任何其他支持的生成器。这样你就得到了与契约完全一致的项目脚手架。

这就是端到端的开源路线：四个工具，四个命令，全部可脚本化。其代价是需要进行配置和衔接。你需要自行维护文件布局、linter 配置、打包步骤以及生成器配置，并且每个工具都有各自的约定。当你想要最大程度的控制力并且不介意处理这些粘合工作时，这种方式非常适用。

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

另一种方法是将设计、数据模型、接口、mock 和 auth 保留在单个项目中，你可以直接在终端中对其进行驱动。apifox-cli 二进制文件是一个完整的项目资源 CLI，而不仅仅是一个测试运行器。它拥有覆盖整个设计层面的命令组：用于数据模型的 schema、用于操作的 endpoint（接口）、用于组织管理的 folder（目录）、用于 auth 的 security-scheme（鉴权组件），以及 import（导入）、export（导出）、mock 等等。

首先需要说明的是：Apifox 不会校验（lint）您的 OpenAPI，也不会强制执行风格指南。这并非它的用途。如果您需要进行校验，请在您的流水线中保留 Spectral 或 vacuum。Apifox 也不是开源的；它是一款带有免费额度的商业产品。它为您提供的是一个集成的项目，因此您无需自己手动拼接设计片段。我们关于 API 设计与测试中 Swagger 替代方案的文章涵盖了这种权衡在何处具有意义。

首先安装并进行身份验证（请参阅安装指南以设置 Token）：

npm install -g apifox-cli
apifox login --with-token <YOUR_ACCESS_TOKEN>

每个命令都会返回结构化的 JSON，并且大多数响应中都包含一个 agentHints.nextSteps 块，用于提示您（或 Agent）下一步要运行什么。在任何命令后添加 --help 即可查看其具体的参数选项。

使用 apifox schema 定义数据模型

设计始于数据。一个可复用的 Order 数据模型会成为接口引用的唯一事实源，这与原始 OpenAPI 中的 components/schemas 概念相同，但它作为项目资源来进行管理。

apifox schema --help
apifox schema create --project <PROJECT_ID>

由于输出是 JSON，您可以通过管道将其传给 jq 以获取新数据模型的 ID，并将其传递给下一个命令。如果您已经有了 OpenAPI 文件，可以直接导入它，而无需重新输入所有内容：

apifox import --project <PROJECT_ID> --file openapi.yaml

apifox import 支持 OpenAPI 3.x、Swagger 2.0、Postman 和 Apifox 格式，因此现有的定义只需一步即可变成一个活跃的项目。

使用 apifox endpoint 定义接口

数据模型准备就绪后，即可添加操作。endpoint 组用于创建和更新接口，并将它们连接到您定义的数据模型以及用于组织它们的目录。

apifox endpoint --help
apifox endpoint list --project <PROJECT_ID>
apifox endpoint create --project <PROJECT_ID>

以 JSON 格式列出接口本身就非常有用。您可以对不同分支之间的输出进行 diff 对比，或者将其传递给一个脚本，以检查每个 path 是否都包含您预期的响应。使用 folder 命令对相关接口进行分组，这样随着项目的增长，项目依然保持易于导航的结构。

使用 apifox security-scheme 定义 auth

Auth 是契约的一部分，而不是事后才考虑的事情。security-scheme 组定义了客户端的鉴权方式：API key、Bearer Token、OAuth 2.0 等。这会映射到 OpenAPI 中的 components/securitySchemes，从而实现导入和导出的无缝往返。

apifox security-scheme --help
apifox security-scheme list --project <PROJECT_ID>

在项目级别定义一次鉴权组件，意味着每个接口都可以引用它，而无需每个操作都重新声明自己的 auth。这正是校验工具通常会要求您保持的一致性。

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

在提交更改或将项目交付给 CI 之前，您需要确保您的资源定义格式正确。CLI 提供了 cli-schema validate 命令，可对照 CLI 期望的数据模型校验定义文件，从而让格式错误的写入尽早失败，而不是在后台静默通过。

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

在您的流水线中将其作为守卫步骤运行：先校验，后应用。非零退出状态码会在损坏的资源进入项目之前中止流水线。这是对您 CLI 写入操作的校验，而不是 OpenAPI 风格检查（linting）；这是两项不同的工作，对于后者您仍然需要使用 Spectral。

导出回 OpenAPI

在 Apifox 中进行设计，然后将标准的产物交付给工具链的其余部分。apifox export 可导出 OpenAPI、HTML、Markdown 或 Postman 格式的文件。

apifox export --project <PROJECT_ID> --format openapi -o dist/openapi.yaml

现在，您又获得了一个可移植的 OpenAPI 文件。您可以将其传给 Spectral 进行风格检查（linting），传给 openapi-generator 生成桩代码（stubs），或者导入到您的文档构建中。一体化项目与开放工具链并不互斥，导出就是连接它们之间的桥梁。

接入 CI

这两种路径在流水线中都表现出色，因为每个命令都有退出状态码和文本输出。一个最小化的设计检查任务可能会依次运行 linter 进行检查，接着进行校验，然后打包：

# fail on style violations
spectral lint openapi.yaml

# validate any CLI resource writes before applying
apifox cli-schema validate --file resource.json

# flatten to a single artifact for downstream steps
redocly bundle openapi.yaml -o dist/openapi.bundled.yaml

由于 Apifox 的输出是包含 agentHints.nextSteps 的 JSON，因此该流程也可以由 AI 编码 Agent 轻松驱动。Agent 读取结构化结果，获取建议的下一步操作并直接执行，无需对 GUI 进行屏幕截图识别。这正是最初采用 CLI 进行设计的初衷：人类可以键入的内容，脚本或 Agent 同样可以。

常见问题

拆分文件会破坏下游工具。 将定义分散在多个 $ref 文件中对人类阅读非常友好，但对生成器来说却很棘手。在生成代码或发布文档之前，请务必将其打包（bundle）为单个文件。可以使用 redocly bundle 来解决此问题。

期望 Apifox 执行风格检查，但它并不会。 Apifox 用于管理资源；它不会强制执行风格指南，也不会标记 OpenAPI 规则违规。为此，请继续使用 Spectral 或 vacuum。将 apifox cli-schema validate 误认为是 linter 是常见的混淆；它校验的是资源结构，而非 OpenAPI 风格。

在编辑前忘记导入。 如果您正在通过 CLI 编辑现有 API，请先将源定义导入到项目中。如果直接编辑一个空项目并期望之前的接口还在，很容易让人产生困惑。

在每个接口上单独定义 auth，而不是统一配置。 应当在项目级别定义 security-scheme（鉴权组件）并进行引用。在每个操作上重复声明 auth 是导致契约偏离的根源。

总结

通过 CLI 设计 API 可以将繁琐的点击操作转变为一套可重复的命令。开放路线（编写、使用 Spectral 进行 lint 校验、使用 Redocly 打包、使用 openapi-generator 生成）为您提供了完全的控制权，且无厂商锁定。而 Apifox CLI 路线则为您提供了一个集成的项目，其中数据模型、接口和 auth 共存，并且每个命令都会返回 Agent 就绪的 JSON。导出功能连接了这两者，因此您永远不会被困住。

选择适合您团队的路线。如果您已经习惯使用 Git 和一堆单一用途的工具，请继续使用它们，并在需要可移植产物时添加 apifox export。如果您不想维护这些粘合代码，请下载 Apifox，安装 CLI，然后无需使用鼠标即可设计您的下一个 API。