api-design-expert
Expert in RESTful API design, OpenAPI/Swagger documentation, versioning, error handling, and API best practices for NestJS applications. Use when designing API endpoints, building RESTful APIs, writing OpenAPI/Swagger docs, implementing versioning, or designing error responses and DTOs.
来源信息
- 仓库
- shipshitdev/shipcode
- 最近来源活动
- 2026年7月10日 11:20
- 检测到的 SKILL.md 语言
- 英语
- 星标
- 7
- 分支
- 1
安装方式
默认使用会先检查来源的 Prompt；你也可以切换为直接命令，或下载本地副本。
检查来源文件
决定是否安装前，请先阅读 SKILL.md，以及 SkillsMP 当前展示的配套文件。
文件资源管理器
3 个文件正在显示 SKILL.md
SKILL.md
来源说明 · 只读预览- name
- api-design-expert
- description
- Expert in RESTful API design, OpenAPI/Swagger documentation, versioning, error handling, and API best practices for NestJS applications. Use when designing API endpoints, building RESTful APIs, writing OpenAPI/Swagger docs, implementing versioning, or designing error responses and DTOs.
- metadata
- {"version":"1.0.0","tags":"api, rest, design"}
# API Design Expert Skill
## When to Use
- Designing new API endpoints
- Creating RESTful APIs
- Writing OpenAPI/Swagger documentation
- Implementing API versioning
- Designing error responses
- Creating DTOs and validation
- Implementing pagination, filtering, sorting
## Project Context Discovery
Before providing guidance:
1. Check `.agents/memory/` for API patterns and architecture notes
2. Review existing controllers and DTOs
3. Check for OpenAPI/Swagger setup
4. Review versioning strategy
## Core Principles
### RESTful Design
```typescript
// 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 Status Codes
- `200 OK` / `201 Created` / `204 No Content`
- `400 Bad Request` / `401 Unauthorized` / `403 Forbidden`
- `404 Not Found` / `409 Conflict` / `500 Internal Server Error`
### Response Format
```typescript
// Single resource
{ "data": {...}, "meta": {...} }
// List with pagination
{ "data": [...], "pagination": { "page", "limit", "total" } }
```
### Error Format
```typescript
{
"error": {
"code": "VALIDATION_ERROR",
"message": "Validation failed",
"details": [...],
"timestamp": "...",
"path": "/api/users"
}
}
```
## Best Practices
- Consistent naming conventions
- Validate all inputs with DTOs
- OpenAPI/Swagger documentation
- Authentication on all endpoints
- Pagination for lists
- Version APIs from the start
---
**For complete DTO examples, pagination/filtering/sorting patterns, versioning strategies, OpenAPI setup, CRUD controller patterns, nested resources, bulk operations, and anti-patterns, see:** `references/full-guide.md`
在 GitHub 查看