API Documentation Generation and Maintenance

API documentation isn’t written once and done — interfaces change, parameters change, return values change, but docs often lag behind code. This case shows how to use LanMate to extract API definitions from code, generate structured API documentation, and keep changelogs updated when interfaces change.

Skills Used

Built-in skills (installed with LanMate, ready out of the box): Word documents (lanmate-docx), HTML reports (lanmate-html-report)
Skill Store: Technical Writing — guide technical content structure, code example writing, and audience adaptation; Markdown Converter — bidirectional conversion between Markdown and HTML, supporting tables, code blocks, and more

Pain Points

Docs are out of sync with code: the interface changed but the docs weren’t updated — callers only find out when they hit issues
API definitions are scattered: routes, parameters, and return values must be pieced together across multiple files
Changes go unrecorded: which version added a parameter, which version deprecated an interface — all passed by word of mouth
Call examples are missing: only interface signatures, with no copyable request / response examples

Recommended Workflow

Step	What LanMate Does	What You Need to Confirm
1	Read code files, extract API definitions (routes, request methods, parameters, return values)	Whether the extracted API info matches the code
2	Generate structured API documentation (interface description + request / response examples + error code table)	Whether examples can be called directly for verification
3	Compare old and new code versions, identify API changes (added / modified / deprecated)	Whether change classification is accurate
4	Generate a changelog (version number + change type + impact description + migration guidance)	Whether the changelog covers what callers need to know
5	Output API documentation Word + changelog HTML	Whether the format is ready for distribution

Prompt Examples

Extract API Definitions

Please read the code files in the src/ directory, extract all API definitions, and organize them into a table:
- API name and function description
- Request path and method (GET / POST / PUT / DELETE)
- Request parameters (name, type, required, description)
- Response structure (field name, type, description)
- Authentication method (Token / API Key / none)
- Error codes and meanings

Read interface definitions, comments, and type declarations in the code to extract information.
For function descriptions not commented in the code, infer from the interface logic and mark "(inferred)."
Output a Word API inventory.

Generate API Documentation

Please generate a complete API document based on the extracted API definitions. Each API should include:
1. API overview: function description and applicable scenarios
2. Request format: path, method, headers, request parameter table
3. Request example: a copyable complete request (with realistic parameter values)
4. Response format: return value structure table
5. Response example: both success and failure responses
6. Error code table: error code, meaning, handling suggestion

Use reasonable example data for parameter values in request examples — do not use "xxx" or "test" placeholders.
Output a self-contained HTML document.

API Change Comparison

Please compare the code in the src/ directory (current version) and the src-v1/ directory (previous version),
identify API changes, and categorize them:
- Added APIs: newly appearing API paths
- Modified APIs: APIs with changed parameters, return values, or behavior
- Deprecated APIs: deleted or marked-as-deprecated APIs

For each change, output:
- API name and path
- Change type (added / modified / deprecated)
- Change details (what changed)
- Impact scope (which callers may be affected)
- Migration guidance (how to adapt for modified APIs)

For impact scopes that cannot be determined from the code diff, mark "TBC" — do not speculate.
Output an HTML change report.

Generate Changelog

Please generate a changelog based on the API change comparison results, including:
- Version number and release date
- Change summary (N APIs added, M APIs modified, K APIs deprecated)
- Itemized change records (API, change type, details, migration guidance)
- Breaking change flags (changes requiring immediate caller adaptation pinned at the top)

Deprecated APIs must include an estimated sunset date — if not specified in the code, write "TBC."
Output a Markdown changelog, then use the Markdown Converter to output an HTML version.

Acceptance Criteria

Extracted API definitions match the code; inferred content is marked
API documentation includes request and response examples for each API, with reasonable, verifiable parameter values
Change comparison covers all API changes with accurate classification
The changelog includes migration guidance; breaking changes are pinned at the top
Deprecated APIs include an estimated sunset date; unspecified ones are marked “TBC”

Common Mistakes

Common Mistake	Why It Happens	Better Practice
Docs out of sync with code	Maintaining docs manually; forgetting to update docs when changing code	Extract API definitions from code to keep docs in sync with code
Examples use placeholders	Taking shortcuts by filling with “xxx”	Use reasonable example data so callers can copy and verify directly
Changes recorded without classification	All changes mixed together, with no visible impact	Classify by added / modified / deprecated; flag breaking changes
Deprecated APIs have no sunset date	Code is marked deprecated but no date is written	Include an estimated sunset date; if not in the code, write “TBC”
Changelog has no migration guidance	Only records what changed, not what callers should do	Attach migration guidance to each modified-API change