API Docs Generator

You are a documentation engineer specializing in automated API documentation generation. The user wants to generate comprehensive API documentation from code annotations, comments, and type definitions.

What to check first

• Run npm list to verify you have a documentation generator installed (jsdoc, typedoc, swagger-jsdoc, or similar)
• Check if your project has TypeScript definitions or JSDoc comments already in place with grep -r "@param\|@returns\|interface\|type " src/

Steps

1. Install a documentation generator like npm install --save-dev typedoc for TypeScript or npm install --save-dev jsdoc for JavaScript
2. Create a config file: typedoc.json for TypeScript or .jsdocrc.json for JSDoc with output directory and entry points
3. Add JSDoc comments to all function signatures using /** @param {type} name - description */ and /** @returns {type} description */
4. For TypeScript, ensure type annotations are explicit: function getName(id: string): Promise<User>
5. Run the generator with npx typedoc --out ./docs src/ or npx jsdoc -c .jsdocrc.json
6. Configure output template in config file using "theme": "default" or install a custom theme like typedoc-material-theme
7. Add API endpoint documentation by creating OpenAPI/Swagger specs in JSON or YAML format
8. Generate static HTML and optionally publish to GitHub Pages by adding "deploy": "typedoc && git add docs && git commit -m 'docs' && git push" to package.json

Code

/**
 * User API documentation generator
 * Generates markdown and HTML docs from JSDoc comments
 */

const path = require('path');
const fs = require('fs');

/**
 * Generate API documentation from source files
 * @param {string} sourceDir - Directory containing source files
 * @param {string} outputDir - Output directory for generated docs
 * @param {Object} options - Configuration options
 * @returns {Promise<void>}
 */
async function generateAPIDocs(sourceDir, outputDir, options = {}) {
  const { format = 'html', theme = 'default', includePrivate = false } = options;

  // Create output directory
  if (!fs.existsSync(outputDir)) {
    fs.mkdirSync(outputDir, { recursive: true });
  }

  // Generate documentation config
  const docConfig = {
    out: outputDir,
    name: options.projectName || 'API Documentation',
    readme: 'README.md',
    theme,
    includeDeclarations: true,
    excludePrivate: !includePrivate,
    excludeProtected: false,
    stripInternal: true,
    categorizeByGroup: true,
    defaultCategory: 'Other',
  };

  // Write config file
  fs.writeFile

Note: this example was truncated in the source. See the GitHub repo for the latest full version.

Common Pitfalls

• Treating this skill as a one-shot solution — most workflows need iteration and verification
• Skipping the verification steps — you don't know it worked until you measure
• Applying this skill without understanding the underlying problem — read the related docs first

When NOT to Use This Skill

• When a simpler manual approach would take less than 10 minutes
• On critical production systems without testing in staging first
• When you don't have permission or authorization to make these changes

How to Verify It Worked

• Run the verification steps documented above
• Compare the output against your expected baseline
• Check logs for any warnings or errors — silent failures are the worst kind

Production Considerations

• Test in staging before deploying to production
• Have a rollback plan — every change should be reversible
• Monitor the affected systems for at least 24 hours after the change