133 lines
3.9 KiB
Markdown
133 lines
3.9 KiB
Markdown
---
|
|
description: Analyze API documentation for endpoints, data types, and request/response formats
|
|
allowed-tools: Task, Read, Bash
|
|
---
|
|
|
|
## Mission
|
|
|
|
Provide comprehensive API documentation analysis for the Tenant Management Portal API by leveraging the api-analyst agent. Answer questions about endpoints, data structures, authentication, and usage patterns.
|
|
|
|
## User Query
|
|
|
|
{{ARGS}}
|
|
|
|
## Workflow
|
|
|
|
### STEP 1: Parse User Query
|
|
|
|
Analyze the user's question to determine what they need:
|
|
|
|
- **Endpoint information**: Specific API routes, methods, parameters
|
|
- **Data type clarification**: TypeScript interfaces, field types, validation rules
|
|
- **Authentication/Authorization**: How to authenticate requests, required headers
|
|
- **Error handling**: Expected error responses, status codes
|
|
- **Integration guidance**: How to integrate with the API, example requests
|
|
- **General overview**: High-level API structure and available resources
|
|
|
|
### STEP 2: Launch API Documentation Analyzer
|
|
|
|
Use the Task tool with `subagent_type: "frontend:api-analyst"` and provide a detailed prompt:
|
|
|
|
```
|
|
The user is asking: {{ARGS}}
|
|
|
|
Please analyze the Tenant Management Portal API documentation to answer this query.
|
|
|
|
Provide:
|
|
1. **Relevant Endpoints**: List all endpoints related to the query with HTTP methods
|
|
2. **Request Format**: Show request body/query parameters with types
|
|
3. **Response Format**: Show response structure with data types
|
|
4. **TypeScript Types**: Generate TypeScript interfaces for request/response
|
|
5. **Authentication**: Specify any auth requirements
|
|
6. **Examples**: Include example requests/responses
|
|
7. **Error Handling**: List possible error responses
|
|
8. **Usage Notes**: Any important considerations or best practices
|
|
|
|
Context:
|
|
- This is for a React + TypeScript frontend application
|
|
- We use TanStack Query for data fetching
|
|
- We need type-safe API integration
|
|
- Current mock API will be replaced with real API calls
|
|
```
|
|
|
|
### STEP 3: Format and Present Results
|
|
|
|
After the agent returns its analysis:
|
|
|
|
1. **Structure the output clearly** with section headers
|
|
2. **Include code examples** in TypeScript
|
|
3. **Highlight important notes** about authentication, validation, etc.
|
|
4. **Provide actionable guidance** for implementation
|
|
|
|
## Expected Output Format
|
|
|
|
The agent should provide documentation analysis structured like:
|
|
|
|
```markdown
|
|
# API Documentation: [Topic]
|
|
|
|
## Endpoints
|
|
|
|
### [HTTP METHOD] /api/[resource]
|
|
- **Purpose**: [Description]
|
|
- **Authentication**: [Required/Optional + method]
|
|
- **Request Parameters**: [Details]
|
|
- **Response**: [Structure]
|
|
|
|
## TypeScript Types
|
|
|
|
\`\`\`typescript
|
|
interface [Resource] {
|
|
id: string;
|
|
// ... fields with types
|
|
}
|
|
|
|
interface [ResourceRequest] {
|
|
// ... request body structure
|
|
}
|
|
\`\`\`
|
|
|
|
## Example Usage
|
|
|
|
\`\`\`typescript
|
|
// Example request with TanStack Query
|
|
const { data } = useQuery({
|
|
queryKey: ['resource', params],
|
|
queryFn: () => api.getResource(params)
|
|
})
|
|
\`\`\`
|
|
|
|
## Error Responses
|
|
|
|
- **400 Bad Request**: [When this occurs]
|
|
- **401 Unauthorized**: [When this occurs]
|
|
- **404 Not Found**: [When this occurs]
|
|
|
|
## Implementation Notes
|
|
|
|
- [Important considerations]
|
|
- [Best practices]
|
|
```
|
|
|
|
## Special Cases
|
|
|
|
### Vague Query
|
|
If the query is general (e.g., "show me the API"), provide an overview of all major resource groups and suggest specific queries.
|
|
|
|
### Multiple Endpoints
|
|
If multiple endpoints are relevant, prioritize by:
|
|
1. Exact match to query
|
|
2. Most commonly used
|
|
3. Related operations (CRUD set)
|
|
|
|
### Missing Documentation
|
|
If documentation is incomplete or unclear, note this explicitly and provide best-effort analysis based on available information.
|
|
|
|
## Notes
|
|
|
|
- Always use the latest API documentation from the OpenAPI spec
|
|
- Prefer TypeScript types over generic JSON examples
|
|
- Include practical usage examples with TanStack Query when relevant
|
|
- Highlight any breaking changes or deprecations
|
|
- Consider the frontend context (React + TypeScript) when providing guidance
|