什么是 API 开发？

API 开发技能作为 Openclaw Skills 生态系统中的主编排器，负责协调专门的代理以处理复杂的后端工作流。它不仅限于简单的代码生成，还将资源建模、安全实施和文档标准整合到一个统一、衔接的流水线中。

通过利用此技能，开发人员可以确保其服务保持一致性、可扩展性和安全性。它自动完成设计阶段与实现阶段之间的过渡，确保最终产品严格遵守定义的 OpenAPI 规范和组织最佳实践。

下载入口:https://github.com/openclaw/skills/tree/main/skills/wpank/api-development

安装与下载

1. ClawHub CLI

从源直接安装技能的最快方式。

2. 手动安装

将技能文件夹复制到以下位置之一

优先级：工作区 > 本地 > 内置

3. 提示词安装

将此提示词复制到 OpenClaw 即可自动安装。

API 开发 应用场景

• 使用 Openclaw Skills 从头开始创建新的 REST、GraphQL 或 gRPC 服务。
• 通过新的、经过验证的端点和模式扩展现有的遗留系统。
• 在微服务之间标准化 API 版本控制和迁移策略。
• 自动生成易于阅读的文档和客户端 SDK 片段。

1. 通过集成设计阶段建立资源模型和 HTTP 语义。
2. 生成机器可读的 OpenAPI 3.x 规范，作为唯一事实来源。
3. 构建按资源分组的路由文件、类型定义和验证模式。
4. 实现具有内置授权和错误处理的服务层业务逻辑。
5. 执行单元测试、集成测试和契约测试，以确保符合规范。
6. 生成全面的开发人员文档，包括使用示例和变更日志。
7. 通过 Openclaw Skills 编排引擎执行版本控制策略和部署工作流。

API 开发 配置指南

要激活此元技能的全部潜力，请确保您的环境中具有核心路由依赖项。您可以通过运行以下命令初始化工作区：

# 在项目中初始化 API 开发环境
openclaw skill add api-development

确保以下支持性的 Openclaw Skills 也可访问：api-design、api-versioning 和 auth-patterns。

API 开发 数据架构与分类体系

该技能在整个生命周期中管理各种技术产物。以下是标准的数据组织方式：

name: api-development
model: reasoning
description: Meta-skill that orchestrates the full API development lifecycle — from design through documentation — by coordinating specialized skills, agents, and commands into a seamless build workflow.

API Development

Orchestrate the full API development lifecycle by coordinating design, implementation, testing, and documentation into a single workflow.

When to Use This Skill

• Building a new API from scratch
• Adding endpoints to an existing API
• Redesigning or refactoring an API
• Planning API versioning and migration
• Running a complete API development cycle (design → build → test → document → deploy)

Orchestration Flow

Follow these steps in order. Each step routes to the appropriate skill or tool.

1. Design the API

Load the api-design skill to establish resource models, URL structure, HTTP method semantics, error formats, and pagination strategy.

Deliverables: Resource list, endpoint map, request/response schemas, error format

2. Generate OpenAPI Spec

Produce a machine-readable OpenAPI 3.x specification from the design. Use the OpenAPI template in api-design/assets/openapi-template.yaml as a starting point.

Deliverables: openapi.yaml with all endpoints, schemas, auth schemes, and examples

3. Scaffold Endpoints

Generate route files, request/response types, and validation schemas for each endpoint. Group routes by resource.

Deliverables: Route files, type definitions, validation schemas per resource

4. Implement Business Logic

Write service-layer logic with input validation, authorization checks, database queries, and proper error propagation. Keep controllers thin — business logic lives in the service layer.

Deliverables: Service modules, repository layer, middleware (auth, rate limiting, CORS)

5. Test

Write tests at three levels:

• Unit tests — service logic, validation, error handling
• Integration tests — endpoint behavior with real DB
• Contract tests — response shapes match OpenAPI spec

Deliverables: Test suite with coverage for happy paths, error cases, edge cases, and auth

6. Document

Generate human-readable API documentation with usage examples and SDK snippets. Ensure every endpoint has description, parameters, request/response examples, and error codes.

Deliverables: API docs, changelog, authentication guide

7. Version and Deploy

Apply a versioning strategy, tag the release, update changelogs, and deploy through the pipeline. Follow the api-versioning skill for deprecation and migration guidance.

Deliverables: Version tag, changelog entry, deployment confirmation

API Design Decision Table

Choose the right paradigm for your use case.

Rule of thumb: Default to REST for public APIs. Use GraphQL when clients need flexible queries across related data. Use gRPC for internal service-to-service communication.

API Checklist

Run through this checklist before marking any API work as complete.

Authentication & Authorization

• Authentication mechanism chosen (JWT, OAuth2, API key)
• Authorization rules enforced at every endpoint
• Tokens validated and scoped correctly
• Secrets stored securely (never in code or logs)

Rate Limiting

• Rate limits configured per endpoint or consumer tier
• RateLimit-* headers included in responses
• 429 Too Many Requests returned with Retry-After header
• Rate limit strategy documented for consumers

Pagination

• All collection endpoints paginated
• Pagination style chosen (cursor-based or offset-based)
• page_size bounded with a sensible maximum
• Total count or hasNextPage indicator included

Filtering & Sorting

• Filter parameters validated and sanitized
• Sort fields allow-listed (no arbitrary column sorting)
• Default sort order defined and documented

Error Handling

• Consistent error response schema across all endpoints
• Correct HTTP status codes (4xx for client, 5xx for server)
• Validation errors return field-level detail
• Internal errors never leak stack traces or sensitive data

Versioning

• Versioning strategy selected and applied uniformly
• Breaking vs non-breaking change policy documented
• Deprecation timeline communicated via Sunset header

CORS

• Allowed origins configured (no wildcard * in production with credentials)
• Allowed methods and headers explicitly listed
• Preflight (OPTIONS) requests handled correctly

Documentation

• OpenAPI / Swagger spec generated and up to date
• Every endpoint has description, parameters, and example responses
• Authentication requirements documented
• Error codes and meanings listed
• Changelog maintained for each version

Security

• Input validation on all fields
• SQL injection prevention
• HTTPS enforced
• Sensitive data never in URLs or logs
• CORS configured correctly

Monitoring

• Structured logging with request IDs
• Error tracking configured (Sentry, Datadog, etc.)
• Performance metrics collected (latency, error rate)
• Health check endpoint available (/health)
• Alerts configured for error rate spikes

Skill Routing Table

NEVER Do

1. NEVER skip the design phase — jumping straight to code produces inconsistent APIs that are expensive to fix
2. NEVER expose database schema directly — API resources are not database tables; design around consumer use cases
3. NEVER ship without authentication — every production endpoint must have an auth strategy
4. NEVER return inconsistent error formats — every error response must follow the same schema
5. NEVER break a published API without a versioning plan — breaking changes require a new version, migration guide, and deprecation timeline
6. NEVER deploy without tests and documentation — untested APIs ship bugs, undocumented APIs frustrate developers