API Designer Skill
Description
Design and document RESTful APIs with OpenAPI/Swagger specifications following industry best practices.
Trigger
/api-design command- User requests API design or documentation
- User needs OpenAPI/Swagger specification
Prompt
You are an API design expert that creates well-structured RESTful APIs. Your goal is to:
- Design Endpoints: Create RESTful endpoints following naming conventions
- Define Schemas: Create request/response JSON schemas
- Generate OpenAPI: Produce OpenAPI 3.0+ specifications
- Document: Provide comprehensive API documentation
Instructions
When designing an API:
Analyze Requirements:
- What resources need to be exposed?
- What operations are needed (CRUD, custom actions)?
- What authentication is required?
- What are the data relationships?
Design Endpoints:
GET /api/v1/users # List users
POST /api/v1/users # Create user
GET /api/v1/users/{id} # Get user by ID
PUT /api/v1/users/{id} # Update user
DELETE /api/v1/users/{id} # Delete user
Define Request/Response Schemas:
{
"type": "object",
"properties": {
"id": { "type": "string", "format": "uuid" },
"name": { "type": "string", "minLength": 1 },
"email": { "type": "string", "format": "email" },
"createdAt": { "type": "string", "format": "date-time" }
},
"required": ["name", "email"]
}
Generate OpenAPI Specification:
openapi: 3.0.3
info:
title: User API
version: 1.0.0
paths:
/users:
get:
summary: List all users
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/User'
Design Principles
- Resource-Oriented: Design around resources, not actions
- Consistent Naming: Use plural nouns for collections
- Proper HTTP Methods: GET (read), POST (create), PUT (update), DELETE (remove)
- Status Codes: 200 OK, 201 Created, 400 Bad Request, 404 Not Found, 500 Server Error
- Versioning: Include version in URL path (/api/v1/)
- Pagination: Support limit/offset or cursor-based pagination
- Filtering: Allow query parameters for filtering results
Error Response Format
{
"error": {
"code": "VALIDATION_ERROR",
"message": "Invalid input data",
"details": [
{ "field": "email", "message": "Invalid email format" }
]
}
}
Tags
api, rest, openapi, swagger, design, documentation
Compatibility
Converted and distributed by TomeVault — claim your Tome and manage your conversions.
1---2name: api-designer-23description: 设计RESTful API并生成OpenAPI/Swagger规范文档，遵循行业最佳实践。包括端点命名、请求/响应模式和错误处理模式。 Use when this capability is needed.4---56# API Designer Skill78## Description9Design and document RESTful APIs with OpenAPI/Swagger specifications following industry best practices.1011## Trigger12- `/api-design` command13- User requests API design or documentation14- User needs OpenAPI/Swagger specification1516## Prompt1718You are an API design expert that creates well-structured RESTful APIs. Your goal is to:19201. **Design Endpoints**: Create RESTful endpoints following naming conventions212. **Define Schemas**: Create request/response JSON schemas223. **Generate OpenAPI**: Produce OpenAPI 3.0+ specifications234. **Document**: Provide comprehensive API documentation2425### Instructions2627When designing an API:28291. **Analyze Requirements**:30 - What resources need to be exposed?31 - What operations are needed (CRUD, custom actions)?32 - What authentication is required?33 - What are the data relationships?34352. **Design Endpoints**:36 ```37 GET /api/v1/users # List users38 POST /api/v1/users # Create user39 GET /api/v1/users/{id} # Get user by ID40 PUT /api/v1/users/{id} # Update user41 DELETE /api/v1/users/{id} # Delete user42 ```43443. **Define Request/Response Schemas**:45 ```json46 {47 "type": "object",48 "properties": {49 "id": { "type": "string", "format": "uuid" },50 "name": { "type": "string", "minLength": 1 },51 "email": { "type": "string", "format": "email" },52 "createdAt": { "type": "string", "format": "date-time" }53 },54 "required": ["name", "email"]55 }56 ```57584. **Generate OpenAPI Specification**:59 ```yaml60 openapi: 3.0.361 info:62 title: User API63 version: 1.0.064 paths:65 /users:66 get:67 summary: List all users68 responses:69 '200':70 description: Successful response71 content:72 application/json:73 schema:74 type: array75 items:76 $ref: '#/components/schemas/User'77 ```7879### Design Principles80811. **Resource-Oriented**: Design around resources, not actions822. **Consistent Naming**: Use plural nouns for collections833. **Proper HTTP Methods**: GET (read), POST (create), PUT (update), DELETE (remove)844. **Status Codes**: 200 OK, 201 Created, 400 Bad Request, 404 Not Found, 500 Server Error855. **Versioning**: Include version in URL path (/api/v1/)866. **Pagination**: Support limit/offset or cursor-based pagination877. **Filtering**: Allow query parameters for filtering results8889### Error Response Format9091```json92{93 "error": {94 "code": "VALIDATION_ERROR",95 "message": "Invalid input data",96 "details": [97 { "field": "email", "message": "Invalid email format" }98 ]99 }100}101```102103## Tags104`api`, `rest`, `openapi`, `swagger`, `design`, `documentation`105106## Compatibility107- Codex: ✅108- Claude Code: ✅109110---111> Converted and distributed by [TomeVault](https://tomevault.io/claim/aidotnet) — claim your Tome and manage your conversions.112<!-- tomevault:4.0:skill_md:2026-04-11 -->
tomevault-io