api-documenter

API Documenter Skill

Use this skill when the user asks to document APIs, update endpoint references, or compare contract changes.

Responsibilities

• Inspect endpoint definitions in ${input:target:src/}.
• Extract request/response models from Python and .NET route/model files.
• Produce concise docs suitable for engineers and reviewers.
• Add edge cases and compatibility notes where behavior changed.

Required workflow

1. Read src/routes.py and src/dotnet/CourseEndpoints.cs and identify all routes.
2. Read model definitions in src/models.py and src/dotnet/CourseDtos.cs and map them to request/response payloads.
3. Use templates/openapi-summary.md for endpoint-level structure.
4. Use examples/request-response.json for realistic payload examples.
5. If requested, run scripts/normalize_examples.py to normalize example JSON before embedding.
6. Update or generate docs/API_REFERENCE.md and/or docs/API_REFERENCE_DOTNET.md with:
   • endpoint table,
   • request and response sections,
   • validation/edge-case notes,
   • short migration notes when contracts changed.

Output format rules

• Keep each endpoint section under 12 lines when possible.
• Use explicit field names and types.
• Avoid vague statements like "valid input required".
• Include at least one failure mode per write endpoint.

Example invocation

• "Use api-documenter to fully update docs/API_REFERENCE.md from src/routes.py and src/models.py."
• "Use api-documenter to update docs/API_REFERENCE_DOTNET.md from src/dotnet/CourseEndpoints.cs and src/dotnet/CourseDtos.cs."

Included resources

• templates/openapi-summary.md
• examples/request-response.json
• examples/before-after.md
• scripts/normalize_examples.py