AutoDocSync

Automated OpenAPI Documentation with AST & Local LLMs

AutoDocSync is a high-performance CLI tool for Express.js developers. It bridges the gap between your source code and documentation by using TypeScript AST (Abstract Syntax Tree) to statically analyze your project and Local AI (Ollama) to generate human-readable endpoint descriptions — entirely on your machine.

[!NOTE] AutoDocSync was built to solve the "Stale Docs" problem. By making documentation generation part of your workflow, your OpenAPI spec stays accurate as your code evolves.

How It Works

AutoDocSync does not guess your routes or rely on manual annotations. It performs a deep static analysis of your Express project to understand exactly how your API behaves.

graph TD
    A[Source Code] --> B{AST Scanner}
    B -- "Express Routes" --> C[Logic Extraction]
    B -- "Mongoose Models" --> D[Schema Parsing]
    C --> E[Context Builder]
    D --> E
    E --> F((Local Ollama))
    F -- "Mistral" --> G[AI Enhancement]
    G --> H[Final OpenAPI 3.0 Spec]

Deep Integration

• AST Parsing — Powered by ts-morph, the scanner traces .use() calls to resolve full URL prefixes and identifies imported handlers and middlewares.
• Payload Extraction — Automatically detects request bodies, query parameters, and URL params directly from your handler logic.
• Smart Schemas — Parses Mongoose models to construct accurate OpenAPI components, including required fields, enums, and contextual examples (e.g., email → [email protected]).
• Privacy-First AI — Uses a local Ollama instance. No API keys, no data sent to the cloud, and zero inference cost.

Quick Start

Follow these steps in order to get AutoDocSync running in your Express project.

Step 1 — Install AutoDocSync

Inside your Express project root, install AutoDocSync as a development dependency:

npm install --save-dev autodocsync

Step 2 — Install Ollama

AutoDocSync uses a locally running Ollama instance to generate AI-powered descriptions.

Download and install Ollama from the official site: https://ollama.com

Once installed, verify it is running:

ollama --version

Step 3 — Pull the Mistral Model

AutoDocSync uses the Mistral model for description generation. Pull it with:

ollama pull mistral

[!TIP] This is a one-time download. Once pulled, the model is cached locally and reused across all future runs.

Step 4 — Generate Your Documentation

With everything set up, run the following command from your Express project root:

npx autodocsync generate . -o ./docs

This scans your project and writes a production-ready openapi.json file to the ./docs directory.

Example Output

Running npx autodocsync generate . -o ./docs on a standard Express + Mongoose project produces a file like docs/openapi.json. Below is a realistic excerpt:

{
  "openapi": "3.0.3",
  "info": {
    "title": "My Backend Service",
    "description": "Industry standard API documentation for professional backend integration.",
    "version": "1.0.0",
    "contact": {
      "name": "Engineering Team Support"
    }
  },
  "servers": [
    {
      "url": "/api/v1",
      "description": "Primary Production/Active version API server"
    }
  ],
  "tags": [
    { "name": "Auth", "description": "Authentication algorithms, secure login, and session management" },
    { "name": "User", "description": "User profile management, account settings, and event registrations" }
  ],
  "paths": {
    "/auth/login": {
      "post": {
        "tags": ["Auth"],
        "summary": "Login user",
        "description": "Authenticates a registered user using their email and password. Returns a signed JWT token and sets an httpOnly access token cookie on success.",
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "email":    { "type": "string", "example": "[email protected]" },
                  "password": { "type": "string", "example": "********" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful operation",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/SuccessResponse" }
              }
            }
          },
          "401": {
            "description": "Action failed due to client or server error",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          }
        }
      }
    },
    "/users/{id}": {
      "get": {
        "tags": ["User"],
        "summary": "Get user by id",
        "description": "Retrieves the full profile of a user by their MongoDB ObjectId. Requires a valid bearer token or session cookie.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": { "type": "string", "example": "60d0fe4f5311236168a109ca" }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful operation",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/SuccessResponse" }
              }
            }
          },
          "404": {
            "description": "Action failed due to client or server error",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "cookieAuth": { "type": "apiKey", "in": "cookie", "name": "accessToken" },
      "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT" }
    },
    "schemas": {
      "SuccessResponse": {
        "type": "object",
        "properties": {
          "success": { "type": "boolean", "example": true },
          "message": { "type": "string", "example": "Operation completed successfully." },
          "data":    { "type": "object", "nullable": true }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "success": { "type": "boolean", "example": false },
          "message": { "type": "string", "example": "Detailed error message explaining the failure." },
          "error":   { "type": "object", "nullable": true }
        }
      }
    }
  },
  "security": [
    { "cookieAuth": [] },
    { "bearerAuth": [] }
  ]
}

[!TIP] Drop the generated openapi.json into Swagger UI or Redoc for instant, interactive API documentation.

CLI Reference

| Command | Argument | Option | Description | | :--- | :--- | :--- | :--- | | generate | [projectDir] | -o, --output <dir> | Scans the project and writes openapi.json to the specified output directory. |

Why AutoDocSync?

| Feature | Benefit | | :--- | :--- | | Real-time accuracy | Docs are always in sync with your actual code — no drift. | | $0 inference cost | Runs on your own hardware. No API subscriptions required. | | OpenAPI 3.0 compliant | Output is compatible with Swagger UI, Redoc, and any standard tooling. | | Zero manual effort | No @swagger JSDoc comments or route decorators needed. |

Project Structure

| Path | Purpose | | :--- | :--- | | bin/index.js | CLI entry point and argument parsing. | | src/scanners/ | AST logic for Express route and Mongoose model parsing. | | src/llm.js | Integration with the local Ollama API. | | src/openapi-gen.js | Core logic for compiling and writing the OpenAPI spec. |

Troubleshooting

| Issue | Resolution | | :--- | :--- | | Ollama is not running | Open the Ollama desktop app or run ollama serve in a separate terminal. | | Model not found | Run ollama pull mistral to download the required model. | | Slow generation or timeout | Large codebases may take a moment. Ensure at least 8 GB of RAM is available and Ollama is idle before running. | | Empty or partial output | Confirm your project uses standard Express route patterns (.get, .post, .use, etc.). |

Contributing

Contributions are welcome. Whether it's adding support for additional frameworks (Fastify, NestJS, Hono) or improving the LLM prompts for better descriptions, feel free to open an issue or submit a pull request.

License

Distributed under the MIT License.

Built for developers who want documentation that actually keeps up with their code.