mcpField
A
api-design-expert

api-design-expert

github.com/shipshitdev开发38203 次安装2 天前更新
代码仓库

关于 api-design-expert

为创建或维护 API 的开发者提供设计指导，涵盖 REST 约定、响应与错误格式、版本管理、验证和文档实践。

主要功能

  1. 01REST 端点设计
  2. 02HTTP 状态码指引
  3. 03响应与错误格式
  4. 04DTO 验证模式
  5. 05版本管理与 OpenAPI 实践

适用场景

  1. 01规划 API 端点
  2. 02统一错误响应
  3. 03设计分页列表 API
  4. 04使用 OpenAPI 编写文档

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/shipshitdev/skills --skill api-design-expert

安装后在 Claude Code 中输入/api-design-expert确认已加载。

附带文件plugin.jsonreferences/full-guide.md

详细介绍

API 设计专家技能

适用场景

  • 设计新的 API 端点
  • 创建 RESTful API
  • 编写 OpenAPI/Swagger 文档
  • 实现 API 版本控制
  • 设计错误响应
  • 创建 DTO 和验证
  • 实现分页、筛选和排序

项目上下文发现

提供指导前：

  1. 检查 .agents/memory/ 中的 API 模式和架构说明
  2. 查看现有控制器和 DTO
  3. 检查 OpenAPI/Swagger 配置
  4. 查看版本控制策略

核心原则

RESTful 设计
// Use nouns, plural, hierarchical
GET    /api/users
GET    /api/users/:id
POST   /api/users
PUT    /api/users/:id
DELETE /api/users/:id
GET    /api/users/:id/posts
HTTP 状态码
  • 200 OK / 201 Created / 204 No Content
  • 400 Bad Request / 401 Unauthorized / 403 Forbidden
  • 404 Not Found / 409 Conflict / 500 Internal Server Error
响应格式
// Single resource
{ "data": {...}, "meta": {...} }

// List with pagination
{ "data": [...], "pagination": { "page", "limit", "total" } }
错误格式
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed",
    "details": [...],
    "timestamp": "...",
    "path": "/api/users"
  }
}

最佳实践

  • 命名约定保持一致
  • 使用 DTO 验证所有输入
  • 编写 OpenAPI/Swagger 文档
  • 为所有端点启用身份验证
  • 为列表提供分页
  • 从一开始就对 API 进行版本控制

如需完整的 DTO 示例、分页/筛选/排序模式、版本控制策略、OpenAPI 配置、CRUD 控制器模式、嵌套资源、批量操作和反模式，请参阅： references/full-guide.md

评论

支持 Markdown