Initial commit
This commit is contained in:
Zhongwei Li
231
skills/api.define/SKILL.md
Normal file
231
skills/api.define/SKILL.md
Normal file
@@ -0,0 +1,231 @@
|
||||
# api.define
|
||||
|
||||
## Overview
|
||||
|
||||
**api.define** scaffolds OpenAPI and AsyncAPI specifications from enterprise-compliant templates, generating production-ready API contracts with best practices built-in.
|
||||
|
||||
## Purpose
|
||||
|
||||
Quickly create API specifications that follow enterprise guidelines:
|
||||
- Generate Zalando-compliant OpenAPI 3.1 specs
|
||||
- Generate AsyncAPI 3.0 specs for event-driven APIs
|
||||
- Include proper error handling (RFC 7807 Problem JSON)
|
||||
- Use correct naming conventions (snake_case)
|
||||
- Include required metadata and security schemes
|
||||
|
||||
## Usage
|
||||
|
||||
### Basic Usage
|
||||
|
||||
```bash
|
||||
python skills/api.define/api_define.py <service_name> [spec_type] [options]
|
||||
```
|
||||
|
||||
### Parameters
|
||||
|
||||
| Parameter | Required | Description | Default |
|
||||
|-----------|----------|-------------|---------|
|
||||
| `service_name` | Yes | Service/API name | - |
|
||||
| `spec_type` | No | openapi or asyncapi | `openapi` |
|
||||
| `--template` | No | Template name | `zalando` |
|
||||
| `--output-dir` | No | Output directory | `specs` |
|
||||
| `--version` | No | API version | `1.0.0` |
|
||||
|
||||
## Examples
|
||||
|
||||
### Example 1: Create Zalando-Compliant OpenAPI Spec
|
||||
|
||||
```bash
|
||||
python skills/api.define/api_define.py user-service openapi --template=zalando
|
||||
```
|
||||
|
||||
**Output**: `specs/user-service.openapi.yaml`
|
||||
|
||||
Generated spec includes:
|
||||
- ✅ Required Zalando metadata (`x-api-id`, `x-audience`)
|
||||
- ✅ CRUD operations for users resource
|
||||
- ✅ RFC 7807 Problem JSON for errors
|
||||
- ✅ snake_case property names
|
||||
- ✅ X-Flow-ID headers for tracing
|
||||
- ✅ Proper HTTP status codes
|
||||
- ✅ JWT authentication scheme
|
||||
|
||||
### Example 2: Create AsyncAPI Spec
|
||||
|
||||
```bash
|
||||
python skills/api.define/api_define.py user-service asyncapi
|
||||
```
|
||||
|
||||
**Output**: `specs/user-service.asyncapi.yaml`
|
||||
|
||||
Generated spec includes:
|
||||
- ✅ Lifecycle events (created, updated, deleted)
|
||||
- ✅ Kafka channel definitions
|
||||
- ✅ Event payload schemas
|
||||
- ✅ Publish/subscribe operations
|
||||
|
||||
### Example 3: Custom Output Directory
|
||||
|
||||
```bash
|
||||
python skills/api.define/api_define.py order-api openapi \
|
||||
--output-dir=api-specs \
|
||||
--version=2.0.0
|
||||
```
|
||||
|
||||
## Generated OpenAPI Structure
|
||||
|
||||
For a service named `user-service`, the generated OpenAPI spec includes:
|
||||
|
||||
**Paths**:
|
||||
- `GET /users` - List users with pagination
|
||||
- `POST /users` - Create new user
|
||||
- `GET /users/{user_id}` - Get user by ID
|
||||
- `PUT /users/{user_id}` - Update user
|
||||
- `DELETE /users/{user_id}` - Delete user
|
||||
|
||||
**Schemas**:
|
||||
- `User` - Main resource schema
|
||||
- `UserCreate` - Creation payload schema
|
||||
- `UserUpdate` - Update payload schema
|
||||
- `Pagination` - Pagination metadata
|
||||
- `Problem` - RFC 7807 error schema
|
||||
|
||||
**Responses**:
|
||||
- `200` - Success (with X-Flow-ID header)
|
||||
- `201` - Created (with Location and X-Flow-ID headers)
|
||||
- `204` - No Content (for deletes)
|
||||
- `400` - Bad Request (application/problem+json)
|
||||
- `404` - Not Found (application/problem+json)
|
||||
- `409` - Conflict (application/problem+json)
|
||||
- `500` - Internal Error (application/problem+json)
|
||||
|
||||
**Security**:
|
||||
- Bearer token authentication (JWT)
|
||||
|
||||
**Required Metadata**:
|
||||
- `x-api-id` - Unique UUID
|
||||
- `x-audience` - Target audience (company-internal)
|
||||
- `contact` - Team contact information
|
||||
|
||||
## Resource Name Extraction
|
||||
|
||||
The skill automatically extracts resource names from service names:
|
||||
|
||||
| Service Name | Resource | Plural |
|
||||
|--------------|----------|--------|
|
||||
| `user-service` | user | users |
|
||||
| `order-api` | order | orders |
|
||||
| `payment-gateway` | payment | payments |
|
||||
|
||||
## Naming Conventions
|
||||
|
||||
The skill automatically applies proper naming:
|
||||
|
||||
| Context | Convention | Example |
|
||||
|---------|------------|---------|
|
||||
| Paths | kebab-case | `/user-profiles` |
|
||||
| Properties | snake_case | `user_id` |
|
||||
| Schemas | TitleCase | `UserProfile` |
|
||||
| Operations | camelCase | `getUserById` |
|
||||
|
||||
## Integration with api.validate
|
||||
|
||||
The generated specs are designed to pass `api.validate` with zero errors:
|
||||
|
||||
```bash
|
||||
# Generate spec
|
||||
python skills/api.define/api_define.py user-service
|
||||
|
||||
# Validate (should pass)
|
||||
python skills/api.validate/api_validate.py specs/user-service.openapi.yaml zalando
|
||||
```
|
||||
|
||||
## Use in Workflows
|
||||
|
||||
```yaml
|
||||
# workflows/api_first_development.yaml
|
||||
steps:
|
||||
- skill: api.define
|
||||
args:
|
||||
- "user-service"
|
||||
- "openapi"
|
||||
- "--template=zalando"
|
||||
output: spec_path
|
||||
|
||||
- skill: api.validate
|
||||
args:
|
||||
- "{spec_path}"
|
||||
- "zalando"
|
||||
required: true
|
||||
```
|
||||
|
||||
## Customization
|
||||
|
||||
After generation, customize the spec:
|
||||
|
||||
1. **Add properties** to schemas:
|
||||
```yaml
|
||||
User:
|
||||
properties:
|
||||
user_id: ...
|
||||
email: # Add this
|
||||
type: string
|
||||
format: email
|
||||
```
|
||||
|
||||
2. **Add operations**:
|
||||
```yaml
|
||||
/users/search: # Add new endpoint
|
||||
post:
|
||||
summary: Search users
|
||||
```
|
||||
|
||||
3. **Modify metadata**:
|
||||
```yaml
|
||||
info:
|
||||
contact:
|
||||
name: Your Team Name # Update this
|
||||
email: team@company.com
|
||||
```
|
||||
|
||||
## Output
|
||||
|
||||
### Success Response
|
||||
|
||||
```json
|
||||
{
|
||||
"status": "success",
|
||||
"data": {
|
||||
"spec_path": "specs/user-service.openapi.yaml",
|
||||
"spec_content": {...},
|
||||
"api_id": "d0184f38-b98d-11e7-9c56-68f728c1ba70",
|
||||
"template_used": "zalando",
|
||||
"service_name": "user-service"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Dependencies
|
||||
|
||||
- **PyYAML**: Required for YAML handling
|
||||
```bash
|
||||
pip install pyyaml
|
||||
```
|
||||
|
||||
## Templates
|
||||
|
||||
| Template | Spec Type | Description |
|
||||
|----------|-----------|-------------|
|
||||
| `zalando` | OpenAPI | Zalando-compliant with all required fields |
|
||||
| `basic` | AsyncAPI | Basic event-driven API structure |
|
||||
|
||||
## See Also
|
||||
|
||||
- [api.validate](../api.validate/SKILL.md) - Validate generated specs
|
||||
- [hook.define](../hook.define/SKILL.md) - Set up automatic validation
|
||||
- [Betty Architecture](../../docs/betty-architecture.md) - Five-layer model
|
||||
- [API-Driven Development](../../docs/api-driven-development.md) - Complete guide
|
||||
|
||||
## Version
|
||||
|
||||
**0.1.0** - Initial implementation with Zalando template support
|
||||
Reference in New Issue
Block a user