{"id":51242499,"url":"https://github.com/phaethix/api-doc-generator","last_synced_at":"2026-06-29T01:30:50.306Z","repository":{"id":367113360,"uuid":"1279196965","full_name":"phaethix/api-doc-generator","owner":"phaethix","description":"AI-powered API documentation generator — describe your API in plain English, get OpenAPI specs + beautiful docs. Built with Deno + React.","archived":false,"fork":false,"pushed_at":"2026-06-24T17:01:20.000Z","size":900,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-24T17:09:01.841Z","etag":null,"topics":["ai","api-documentation","deno","llm","openapi","react","swagger","typescript"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/phaethix.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":"ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-24T13:13:43.000Z","updated_at":"2026-06-24T17:02:05.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/phaethix/api-doc-generator","commit_stats":null,"previous_names":["phaethix/api-doc-generator"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/phaethix/api-doc-generator","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/phaethix%2Fapi-doc-generator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/phaethix%2Fapi-doc-generator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/phaethix%2Fapi-doc-generator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/phaethix%2Fapi-doc-generator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/phaethix","download_url":"https://codeload.github.com/phaethix/api-doc-generator/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/phaethix%2Fapi-doc-generator/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34910177,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-28T02:00:05.809Z","response_time":54,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","api-documentation","deno","llm","openapi","react","swagger","typescript"],"created_at":"2026-06-29T01:30:49.448Z","updated_at":"2026-06-29T01:30:50.292Z","avatar_url":"https://github.com/phaethix.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🧠 API Doc Generator — AI-Powered API Documentation\n\n\u003cdiv align=\"center\"\u003e\n\n**Describe your API in plain English. Get beautiful docs in seconds.**\n\nFrom natural language, OpenAPI specs, or custom definitions → Markdown / HTML / JSON — all running locally, no data ever leaves your server.\n\n[![Deno](https://img.shields.io/badge/Deno-2.x-000000?style=flat\u0026logo=deno)](https://deno.land)\n[![React](https://img.shields.io/badge/React-18-61DAFB?style=flat\u0026logo=react)](https://react.dev)\n[![TypeScript](https://img.shields.io/badge/TypeScript-Strict-3178C6?style=flat\u0026logo=typescript)](https://www.typescriptlang.org)\n[![AI](https://img.shields.io/badge/AI-LLM_Structured_Output-8B5CF6?style=flat)](https://platform.openai.com/docs/guides/structured-outputs)\n[![License](https://img.shields.io/badge/License-MIT-green?style=flat)](LICENSE)\n\n[中文文档](docs/README.zh-CN.md)\n\n\u003c/div\u003e\n\n---\n\n## Why this tool?\n\nMost API doc tools force you to **already have** an OpenAPI spec. You either write it by hand (tedious) or use heavy GUI editors (slow, vendor lock-in). This tool is different:\n\n```mermaid\n%%{init: {'theme': 'base', 'themeVariables': {'primaryColor': '#F1F5F9', 'primaryTextColor': '#1E293B', 'primaryBorderColor': '#CBD5E0', 'lineColor': '#94A3B8', 'secondaryColor': '#FFFFFF', 'tertiaryColor': '#F8FAFC'}}}%%\nflowchart LR\n    subgraph Inputs[\"Input Sources\"]\n        direction TB\n        NL[\"💬 Natural Language\"]\n        OA[\"📋 OpenAPI 3.0\"]\n        CS[\"✏️ Custom JSON\"]\n    end\n\n    subgraph Pipeline[\"Unified Pipeline\"]\n        P[Parser] --\u003e G[Generator] --\u003e R[Renderer]\n    end\n\n    subgraph Outputs[\"Output Formats\"]\n        direction TB\n        MD[\"📄 Markdown\"]\n        HTML[\"🌐 HTML\"]\n        JSON[\"📦 JSON\"]\n    end\n\n    NL --\u003e P\n    OA --\u003e P\n    CS --\u003e P\n    R --\u003e MD\n    R --\u003e HTML\n    R --\u003e JSON\n\n    style Inputs fill:#F8FAFC,stroke:#CBD5E0,stroke-width:1px,color:#1E293B\n    style Pipeline fill:#FFFFFF,stroke:#E2E8F0,stroke-width:1px,color:#1E293B\n    style Outputs fill:#F8FAFC,stroke:#CBD5E0,stroke-width:1px,color:#1E293B\n    classDef nodeIn fill:#F1F5F9,stroke:#64748B,color:#1E293B,stroke-width:1px\n    classDef nodePipe fill:#E2E8F0,stroke:#94A3B8,color:#1E293B,stroke-width:1px\n    classDef nodeOut fill:#F1F5F9,stroke:#64748B,color:#1E293B,stroke-width:1px\n    class NL,OA,CS nodeIn\n    class P,G,R nodePipe\n    class MD,HTML,JSON nodeOut\n```\n\n**Three input paths, one pipeline, zero vendor lock-in.** Pick whichever works for you.\n\n### How we compare\n\n|  | API Doc Generator | Swagger UI | Redoc | Postman | Stoplight |\n|---|---|---|---|---|---|\n| **Natural language → docs** | ✅ AI-powered | ❌ | ❌ | ⚠️ AI Agent (cloud) | ❌ |\n| **Custom spec format** | ✅ simple JSON | ❌ | ❌ | ❌ | ❌ |\n| **Import OpenAPI 3.0** | ✅ | ✅ | ✅ | ✅ | ✅ |\n| **Output Markdown** | ✅ | ❌ | ❌ | ❌ | ❌ |\n| **Output HTML** | ✅ stylish single-page | ✅ interactive | ✅ beautiful | ⚠️ published portal | ✅ interactive |\n| **Output JSON** | ✅ | ❌ | ❌ | ❌ | ❌ |\n| **Streaming AI generation** | ✅ SSE | ❌ | ❌ | ❌ | ❌ |\n| **Self-hosted** | ✅ docker-compose up | ✅ | ✅ | ⚠️ SaaS, local MCP | ⚠️ Enterprise only |\n| **Open source** | ✅ MIT | ✅ Apache 2.0 | ✅ MIT | ❌ | ❌ |\n| **Lightweight** | ✅ ~7k LOC | ✅ | ✅ | ❌ | ❌ |\n\n\u003e **Notes:**\n\u003e - **Swagger UI** is the open-source renderer. SmartBear (its parent company) launched AI-powered spec generation in 2025, but that's a separate cloud product (SwaggerHub), not Swagger UI itself.\n\u003e - **Postman** added Agent Mode (AI) for doc generation, but it consumes AI credits and runs on Postman's cloud. The MCP server is open-source for local bridging, but the core platform is proprietary SaaS.\n\u003e - **Redoc** renders Markdown *within* OpenAPI descriptions but does not output standalone `.md` files.\n\u003e - **Stoplight** is proprietary SaaS. Self-hosted Git integration requires Enterprise plan (custom pricing).\n\n### ✨ Features\n\n- **🧠 AI-powered generation** — Describe your API in plain English, get a valid OpenAPI 3.0 spec. Uses JSON Schema structured output to guarantee correctness, with automatic fallback and local validation.\n- **📋 OpenAPI import** — Already have an OpenAPI spec? Paste it in and get instant docs.\n- **✏️ Custom spec format** — A lightweight JSON format for when you don't need the full OpenAPI complexity.\n- **📄 Multi-format output** — Generate clean Markdown, stylish standalone HTML, or machine-readable JSON.\n- **⚡ Streaming AI** — Watch the AI generate your API spec in real-time via SSE, with live character count and elapsed time.\n- **🌙 Dark mode** — Full light/dark theme support across the entire UI.\n- **🐳 One-command deploy** — `docker-compose up --build` and you're running.\n- **🔒 Data never leaves your server** — All processing is local. No cloud, no telemetry, no vendor lock-in.\n- **🏗️ Clean architecture** — Deno backend + React frontend + standalone GenAI module. Each layer independently testable.\n- **✅ Production-ready CI** — GitHub Actions with fmt → lint → type-check → test → build on every PR.\n\n### 🖼️ Preview\n\n\u003ctable\u003e\n  \u003ctr\u003e\n    \u003ctd align=\"center\" width=\"50%\"\u003e\n      \u003cimg src=\"assets/screenshots/frontend-main.png\" /\u003e\u003cbr/\u003e\n      \u003cem\u003eStandard Mode — paste a spec, get docs\u003c/em\u003e\n    \u003c/td\u003e\n    \u003ctd align=\"center\" width=\"50%\"\u003e\n      \u003cimg src=\"assets/screenshots/frontend-ai.png\" /\u003e\u003cbr/\u003e\n      \u003cem\u003eAI Mode — describe in plain English, watch it generate\u003c/em\u003e\n    \u003c/td\u003e\n  \u003c/tr\u003e\n\u003c/table\u003e\n\n### 🏗️ Architecture\n\n```mermaid\n%%{init: {'theme': 'base', 'themeVariables': {'primaryColor': '#F1F5F9', 'primaryTextColor': '#1E293B', 'primaryBorderColor': '#CBD5E0', 'lineColor': '#94A3B8', 'secondaryColor': '#FFFFFF', 'tertiaryColor': '#F8FAFC'}}}%%\nflowchart LR\n    subgraph FE[\"React SPA\"]\n        Editor[JsonEditor]\n        Output[OutputPanel]\n        AIPanel[AI Panel]\n    end\n\n    subgraph BE[\"Deno Backend\"]\n        Route{{URLPattern\u003cbr/\u003eRouter}}\n        subgraph Pipeline[\"Core Pipeline\"]\n            P[Parser] --\u003e G[Generator] --\u003e R[Renderer]\n        end\n        Adapter[(OpenAPI\u003cbr/\u003eAdapter)]\n        AIHandler[AI\u003cbr/\u003eHandlers]\n    end\n\n    subgraph GenAI[\"GenAI Module\"]\n        Client[LLMClient]\n        Provider[ChatCompletions\u003cbr/\u003eProvider]\n        Schema[JSON Schemas]\n    end\n\n    FE --\u003e|POST /generate| Route\n    FE --\u003e|POST /ai/*| Route\n    Route --\u003e P\n    Route -.-\u003e|/import/openapi| Adapter\n    Route -.-\u003e|/ai/*| AIHandler\n    Adapter --\u003e G\n    AIHandler --\u003e Client\n    Client --\u003e Provider\n    Provider --\u003e|LLM API| Ext[External\u003cbr/\u003eLLM API]\n    Schema --\u003e Client\n    R -.-\u003e|Response| FE\n\n    style FE fill:#F8FAFC,stroke:#CBD5E0,stroke-width:1px,color:#1E293B\n    style BE fill:#F8FAFC,stroke:#CBD5E0,stroke-width:1px,color:#1E293B\n    style GenAI fill:#F8FAFC,stroke:#CBD5E0,stroke-width:1px,color:#1E293B\n    style Pipeline fill:#FFFFFF,stroke:#E2E8F0,stroke-width:1px,color:#1E293B\n    classDef nodeFe fill:#F1F5F9,stroke:#64748B,color:#1E293B,stroke-width:1px\n    classDef nodeBe fill:#334155,stroke:#1E293B,color:#F8FAFC,stroke-width:1px\n    classDef nodePipe fill:#E2E8F0,stroke:#94A3B8,color:#1E293B,stroke-width:1px\n    classDef nodeGenAI fill:#E2E8F0,stroke:#94A3B8,color:#1E293B,stroke-width:1px\n    class Editor,Output,AIPanel nodeFe\n    class Route,AIHandler nodeBe\n    class P,G,R nodePipe\n    class Client,Provider,Schema nodeGenAI\n```\n\n### 🚀 Quick Start\n\n#### Prerequisites\n\n- Deno 2.x\n- Node.js 18+\n\n#### One-command setup\n\n```bash\n./scripts/dev.sh start      # Start both frontend \u0026 backend\n./scripts/dev.sh status     # Check status\n./scripts/dev.sh stop       # Stop services\n./scripts/dev.sh restart    # Restart\n```\n\nVisit **http://localhost:8080**\n\n#### Manual setup\n\n```bash\n# Build frontend\ncd frontend \u0026\u0026 npm install \u0026\u0026 npm run build \u0026\u0026 cd ..\n\n# Start backend\ncd backend \u0026\u0026 deno task start\n```\n\n### 📖 API Usage\n\n#### Generate documentation\n\n```bash\nPOST /generate?format=markdown|html|json\n\ncurl -X POST 'http://localhost:8080/generate?format=markdown' \\\n  -H 'Content-Type: application/json' \\\n  -d '{\n    \"info\": { \"title\": \"My API\", \"version\": \"1.0.0\" },\n    \"paths\": {\n      \"/users\": {\n        \"get\": {\n          \"summary\": \"List users\",\n          \"responses\": { \"200\": { \"description\": \"OK\" } }\n        }\n      }\n    }\n  }'\n```\n\n#### Import OpenAPI\n\n```bash\nPOST /import/openapi?format=markdown\n# Send OpenAPI 3.0 JSON directly\n```\n\n#### AI: Ping (test LLM connection)\n\n```bash\nPOST /ai/ping\n# → { \"ok\": true, \"reply\": \"...\", \"model\": \"...\", \"usage\": {...} }\n```\n\n#### AI: Generate OpenAPI from natural language\n\n```bash\nPOST /ai/generate-openapi\nContent-Type: application/json\n\n{\n  \"description\": \"User management system with list users and get user by ID\",\n  \"scope\": \"document\"\n}\n\n# → { \"ok\": true, \"openapi\": {...}, \"scope\": \"document\", \"usage\": {...}, \"format_used\": \"json_schema\" }\n```\n\n#### AI: Streaming generation\n\n```bash\nPOST /ai/generate-openapi-stream\n# Server-Sent Events stream of generation progress\n```\n\n#### Health check\n\n```bash\nGET /health\n# → { \"status\": \"ok\", \"timestamp\": \"...\" }\n```\n\n### 🧪 Testing\n\n```bash\n# Backend tests\ncd backend \u0026\u0026 deno test --allow-net --allow-read --allow-env\n\n# GenAI tests\ncd genai \u0026\u0026 deno test --allow-net --allow-read --allow-env\n```\n\n### 📦 Deployment\n\n#### Docker\n\n```bash\ndocker-compose up --build\n\n# Or build manually\ndocker build -t api-doc-generator .\ndocker run -p 8080:8080 api-doc-generator\n```\n\n### 🔧 Configuration\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `PORT` | 8080 | Server port |\n| `HOST` | 0.0.0.0 | Server host |\n| `OPENAI_API_KEY` | - | LLM API key (required for AI features) |\n| `OPENAI_BASE_URL` | `https://apihub.agnes-ai.com/v1` | LLM API base URL |\n| `LLM_MODEL` | `agnes-2.0-flash` | LLM model name |\n| `LOG_LEVEL` | `info` | Log level |\n| `CORS_ALLOWED_ORIGINS` | `http://localhost:5173,...` | CORS allowed origins |\n\nCopy `config/env.example` to `.env` and modify as needed.\n\n### 🗺️ Roadmap\n\n| Status | Feature |\n|--------|---------|\n| 📋 | **Multiple LLM providers** — OpenAI, Anthropic, Ollama |\n| 📋 | **Swagger 2.0 import** — Support legacy specs |\n| 📋 | **OpenAPI file upload** — Upload `.json`/`.yaml` in UI |\n| 📋 | **YAML output** — Generate docs in YAML |\n| 📋 | **CLI mode** — `npx api-doc-gen spec.json -f markdown` |\n| 📋 | **Custom templates** — User-defined output templates (Handlebars) |\n| 📋 | **Postman collection export** — Export as Postman collection |\n\nSee the full [Roadmap](ROADMAP.md) for details and timelines.\n\n### 🤝 Contributing\n\nContributions are welcome! Whether it's a bug fix, a new LLM provider, or a documentation improvement — we'd love your help.\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, coding standards, and the PR process.\n\nLook for issues labeled [`good-first-issue`](https://github.com/phaethix/api-doc-generator/labels/good-first-issue) to get started.\n\n### 📄 License\n\nMIT — use it, modify it, ship it.\n\n---\n\n\u003cdiv align=\"center\"\u003e\n  \u003csub\u003eBuilt with Deno + React + TypeScript · AI powered · Privacy first\u003c/sub\u003e\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fphaethix%2Fapi-doc-generator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fphaethix%2Fapi-doc-generator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fphaethix%2Fapi-doc-generator/lists"}