api-docs-generator

# API Documentation Generator

## Quick Start

Generate API docs based on code type:

```bash
# OpenAPI from Express routes
npx swagger-jsdoc -d swaggerDef.js routes/*.js

# JSDoc for JavaScript
npx jsdoc src/ -d docs/

# Python docstrings
pdoc --html --output-dir docs/ mypackage/
```

## Instructions

### Step 1: Identify API Type

Determine documentation approach:

| API Type | Tool | Output |
|----------|------|--------|
| REST API | OpenAPI/Swagger | Interactive API docs |
| GraphQL | GraphQL Schema | Schema documentation |
| JavaScript Library | JSDoc | HTML reference |
| Python Library | Sphinx/pdoc | HTML reference |

### Step 2: Extract Documentation

**REST API (OpenAPI):**

Scan route files for JSDoc comments:
```javascript
/**
 * @swagger
 * /users:
 *   get:
 *     summary: Get all users
 *     responses:
 *       200:
 *         description: List of users
 */
router.get('/users', getUsers);
```

Generate spec:
```bash
npx swagger-jsdoc -d swaggerDef.js routes/*.js -o openapi.json
```

**JavaScript Library (JSDoc):**

```javascript
/**
 * Adds two numbers together.
 * @param {number} a - First number
 * @param {number} b - Second number
 * @returns {number} Sum of a and b
 * @example
 * add(2, 3); // returns 5
 */
function add(a, b) {
  return a + b;
}
```

**Python (Docstrings):**

```python
def add(a: int, b: int) -> int:
    """Add two numbers together.
    
    Args:
        a: First number
        b: Second number
        
    Returns:
        Sum of a and b
        
    Example:
        >>> add(2, 3)
        5
    """
    return a + b
```

### Step 3: Generate Documentation

**OpenAPI/Swagger:**
```bash
# Generate OpenAPI spec
npx swagger-jsdoc -d swaggerDef.js routes/*.js -o openapi.json

# Serve interactive docs
npx swagger-ui-express openapi.json
```

**JSDoc:**
```bash
npx jsdoc src/ -d docs/ -r
```

**Python Sphinx:**
```bash
sphinx-apidoc -o docs/source mypackage/
cd docs && make html
```

**Python pdoc:**
```bash
pdoc --html --output-dir doc