api-doc-gen

API Documentation Generation Skill

Trigger

"Generate API docs" / "Update OpenAPI spec" / "Document this endpoint"

Steps

1. Discover API Endpoints

grep -rn "\[Http\(Get\|Post\|Put\|Delete\|Patch\)\]" --include="*.cs" src/

If this step fails (no matches): Try grep -rn "\[Route\|MapGet\|MapPost\|MapPut\|MapDelete" --include="*.cs" src/ for minimal API or attribute routing patterns.

*If no .cs files found: Stop and report "No .NET project found in this directory."

2. Extract Endpoint Details

For each endpoint, document:

• HTTP method and route template (from [HttpGet("route")] or [Route] attributes)
• Request body schema (from parameter types and [FromBody] attributes)
• Query parameters (from [FromQuery] attributes)
• Path parameters (from [FromRoute] attributes)
• Response schema (from return types and [ProducesResponseType] attributes)
• Authentication requirements (from [Authorize] attributes)

3. Generate/Update OpenAPI Spec

openapi: 3.1.0
info:
  title: (project name from .csproj)
  version: (from VERSION file or AssemblyVersion)
paths:
  /api/v1/resource:
    get:
      summary: Brief description
      parameters: [...]
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Resource' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { $ref: '#/components/responses/NotFound' }

4. Validate Consistency

Use the forge_analyze MCP tool to verify spec-to-code consistency:

• Every controller action has a matching spec entry
• No spec entries without corresponding code (ghost endpoints)
• Request/response schemas match actual DTO classes
• Status codes match [ProducesResponseType] attributes
• Auth requirements match [Authorize] / [AllowAnonymous] attributes

5. Report

API Documentation Status:
  Endpoints in code:    N
  Endpoints in spec:    N
  Missing from spec:    N (list them)
  Ghost entries:        N (in spec but not in code)
  Schema mismatches:    N

Overall: PASS / FAIL