arch-api

用途

此技能可帮助 OpenClaw 设计、编写文档并实现 API 架构，重点关注 REST 原则、版本控制策略、HATEOAS、身份验证模式、OpenAPI 规范和 API 网关设计。它可确保 API 具备可扩展性、安全性并符合标准。

使用场景

在设计新的 RESTful API、将旧版 API 迁移到现代标准、实现向后兼容的版本控制，或集成 HATEOAS 以提供超媒体驱动的响应时，请使用此技能。在微服务环境中、为 Swagger UI 生成 OpenAPI 文档，或评估受保护端点的 JWT 等身份验证模式时，也可使用此技能。

主要功能

• REST 设计：生成 URI 结构（例如，/resources/{id}），并将 HTTP 方法（GET、POST）映射到特定响应代码（200 OK、404 Not Found）。
• 版本控制：支持基于 URI（例如，/v1/resources）或基于标头（例如，Accept: application/vnd.myapi.v1+json）的版本控制。
• HATEOAS：在 JSON 响应中添加自身链接和相关资源链接，例如，{"_links": {"self": "/users/1"}}。
• 身份验证模式：实现 JWT 或 OAuth2 流程，包括令牌验证和作用域（例如，read:users）。
• OpenAPI 文档：根据代码或设计自动生成 OpenAPI 3.0 YAML/JSON 规范，包括架构和端点。
• 网关模式：设计 API 网关以进行路由，例如，使用 Kong 或 AWS API Gateway 等模式实现负载均衡。

使用模式

通过 OpenClaw CLI 使用此技能，命令结构为：openclaw arch-api <subcommand> [flags]。运行命令前，务必通过环境变量设置身份验证密钥：export OPENCLAW_API_KEY=your_api_key。交互式使用时，可将输出传递给其他工具，例如：openclaw arch-api design --rest | jq .。复杂输入请使用 JSON 配置文件，格式如下：{"endpoints": [{"path": "/users", "method": "GET"}]}。

要设计 REST API，请运行：openclaw arch-api design --type rest --version v1 --hateoas。要生成 OpenAPI，请提供源文件：openclaw arch-api docs --input api-spec.json --output openapi.yaml。

常用命令/API

• 命令：openclaw arch-api design --rest --endpoints users/get,users/post --version v1 标志：--hateoas 用于启用 HATEOAS 链接；--auth jwt 用于添加 JWT 身份验证。 代码片段：

  openclaw arch-api design --rest > api_design.json
  cat api_design.json | grep "uri"
  

• 命令：openclaw arch-api generate-openapi --from-code ./src/api/controllers.py --output docs/openapi.yaml 标志：--validate 用于检查错误；--gateway kong 用于采用特定于网关的模式。 代码片段：

  export OPENCLAW_API_KEY=abc123
  openclaw arch-api generate-openapi --from-code .
  

• API 端点：如果使用 OpenClaw 的内部 API，请向 /v1/arch-api/design 发送 POST 请求，请求正文为：{"type": "rest", "version": "v1"}。响应包含类似 {"endpoints": [{"path": "/users", "method": "GET"}]} 的 JSON。 配置格式：输入请使用 YAML，例如：

  endpoints:
    - path: /users
      method: GET
      auth: jwt
  

• 命令：openclaw arch-api validate --spec openapi.yaml --check hateoas 标志：--check versioning 用于验证版本标头。

集成说明

通过串联命令将此技能与其他 OpenClaw 技能集成，例如：openclaw chain arch-api se-deployment --input api_design.json。对于外部工具，请将输出导出为文件：openclaw arch-api design > input_for_deployment.txt。如果需要身份验证，请始终在脚本中使用环境变量模式：$OPENCLAW_API_KEY，例如在 bash 脚本中：

#!/bin/bash
export OPENCLAW_API_KEY=your_key
openclaw arch-api design --rest

要共享配置，请使用与 Swagger Editor 等工具兼容的 JSON 文件，并确保字段符合 OpenAPI 架构。

错误处理

检查命令退出代码：如果 openclaw arch-api design 返回非零值，请解析 stderr，查找类似 "Invalid endpoint format" 的消息。对于 API 调用，请处理 HTTP 错误：如果 status == 401，请使用刷新的 $OPENCLAW_API_KEY 重试。在脚本中使用 try-catch：

try {
  openclaw arch-api generate-openapi --input invalid.json
} catch (e) {
  if (e.includes("Validation error")) { console.log("Fix JSON schema"); }
}

常见错误：输入格式错误（例如缺少 --version 标志）时返回 400；$OPENCLAW_API_KEY 无效时返回 403。使用以下命令记录错误：openclaw arch-api design 2>> error.log。

具体使用示例

1. 为用户管理系统设计 REST API：首先，设置你的 auth key：export OPENCLAW_API_KEY=your_key。然后运行：openclaw arch-api design --rest --endpoints users/get,users/post --version v1 --auth jwt --hateoas。这会输出一个 JSON 文件，其中包含类似 {"path": "/users", "method": "GET", "_links": {"self": "/users/1"}} 的端点，你可以用它在代码中构建 API。

2. 为现有代码库生成 OpenAPI 文档：导出你的 key：export OPENCLAW_API_KEY=your_key。执行：openclaw arch-api generate-openapi --from-code ./src/api --gateway aws --output api_docs.yaml。这会创建一个包含规范的 YAML 文件，例如包括 /users 的路径和 JWT 安全方案，可直接用于与 Swagger UI 集成。

图关系

• 相关项目：se-deployment（用于通过网关模式部署设计好的 API）。
• 关联方式：通过 se-architecture 集群关联（共享“api-design”等标签，以支持协作技能）。
• 链接至：se-auth（用于了解 API 中详细的身份验证实现）。
• 相关项目：openapi-tool（用于扩展 OpenAPI 文档生成）。