Prompt file imported from Shamail/ai-coding-template (.windsurf/workflows/generate_api_documentation.md). Copyright stays with the author.

API Documentation Generation Workflow

Overview

This workflow generates comprehensive API documentation from the Hono API source code, making it easier for developers and stakeholders to understand and use the API.

Prerequisites

• Implemented API routes and handlers in packages/api/src
• Proper JSDoc/TSDoc comments in the source code (ideally)

Steps

1. Analyze API Source Code

   • Scan the Hono API source code in packages/api/src
   • Identify all route definitions, handlers, and middleware
   • Extract information from JSDoc/TSDoc comments if available
   • Determine request/response structures for each endpoint

2. Define Documentation Format

   • Choose between OpenAPI specification (YAML) or markdown format
   • Consider the target audience (developers, stakeholders, etc.)
   • Determine the level of detail needed

3. Generate API Documentation Structure

   • Create a documentation outline with sections for:
     • API Overview
     • Authentication and Authorization
     • Base URL and Environments
     • Endpoints grouped by resource or functionality
     • Error Handling and Status Codes
     • Rate Limiting (if applicable)

4. Document Each Endpoint

   • For each API endpoint, document:
     • HTTP Method and Path
     • Description and Purpose
     • Request Parameters (path, query, header)
     • Request Body Schema
     • Response Body Schema
     • Response Status Codes
     • Example Requests and Responses
     • Authentication Requirements
     • Rate Limiting Information (if applicable)

5. Generate Documentation File

   • Use Windsurf AI to compile all the information
   • Format according to chosen standard (OpenAPI or markdown)
   • Include proper metadata and versioning information
   • Store at docs/api_documentation.yaml or docs/api_documentation.md

6. Review and Refine

   • Verify documentation accuracy against the actual implementation
   • Ensure all endpoints are properly documented
   • Check for clarity and completeness
   • Add any missing information or examples

Output

A comprehensive API documentation file (docs/api_documentation.yaml or docs/api_documentation.md) that accurately describes all API endpoints, making it easier for developers to understand and use the API.