openapi-spec-generator 0.1.0__tar.gz

openapi_spec_generator-0.1.0/PKG-INFO

@@ -0,0 +1,98 @@
+Metadata-Version: 2.4
+Name: openapi-spec-generator
+Version: 0.1.0
+Summary: Generate OpenAPI specifications for any REST API project directory.
+License: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: click>=8.0
+Provides-Extra: claude
+Requires-Dist: anthropic>=0.25; extra == "claude"
+Provides-Extra: openai
+Requires-Dist: openai>=1.0; extra == "openai"
+Provides-Extra: all
+Requires-Dist: anthropic>=0.25; extra == "all"
+Requires-Dist: openai>=1.0; extra == "all"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-cov>=5.0; extra == "dev"
+
+# OpenAPI Generator
+
+A pip-installable CLI tool that uses AI to generate OpenAPI 3.0.3 specifications for any REST API project directory.
+
+## Overview
+
+Point this tool at any REST API project and it will scan the source files, send them to an AI model (Claude or OpenAI), and produce a valid OpenAPI 3.0.3 JSON specification.
+
+## Installation
+
+```bash
+# With Claude support (default)
+pip install "openapi-generator[claude]"
+
+# With OpenAI support
+pip install "openapi-generator[openai]"
+
+# Both providers
+pip install "openapi-generator[all]"
+```
+
+## Usage
+
+```bash
+openapi-gen <path-to-project> --api-key <your-api-key>
+```
+
+The API key can also be provided via the `OPENAPI_GEN_API_KEY` environment variable:
+
+```bash
+export OPENAPI_GEN_API_KEY=sk-ant-...
+openapi-gen <path-to-project>
+```
+
+### Options
+
+| Option | Default | Description |
+|---|---|---|
+| `<path>` | _(required)_ | Path to the REST API project directory |
+| `--api-key` | `OPENAPI_GEN_API_KEY` env var | AI provider API key |
+| `--provider` | `claude` | AI provider: `claude` or `openai` |
+| `--output`, `-o` | `openapi.json` | Output file path |
+| `--title` | `API` | API title in the spec |
+| `--version` | `1.0.0` | API version in the spec |
+
+### Examples
+
+```bash
+# Generate a spec using Claude (default)
+export OPENAPI_GEN_API_KEY=sk-ant-...
+openapi-gen ./my-api
+
+# Generate a spec using OpenAI
+openapi-gen ./my-api --provider openai --api-key sk-...
+
+# Specify title, version, and output path
+openapi-gen ./my-api --title "My REST API" --version "2.0.0" --output ./docs/openapi.json
+```
+
+## Output
+
+The generated file follows the [OpenAPI 3.0.3 specification](https://spec.openapis.org/oas/v3.0.3) and can be used directly with tools like Swagger UI, Postman, or any OpenAPI-compatible client generator.
+
+## Supported Languages
+
+The tool scans files with the following extensions: `.py`, `.js`, `.ts`, `.go`, `.java`, `.rb`, `.php`, `.cs`
+
+## Development
+
+```bash
+git clone https://github.com/your-org/openapi-generator
+cd openapi-generator
+pip install -e ".[dev]"
+pytest
+```
+
+## License
+
+MIT

openapi_spec_generator-0.1.0/README.md

@@ -0,0 +1,79 @@
+# OpenAPI Generator
+
+A pip-installable CLI tool that uses AI to generate OpenAPI 3.0.3 specifications for any REST API project directory.
+
+## Overview
+
+Point this tool at any REST API project and it will scan the source files, send them to an AI model (Claude or OpenAI), and produce a valid OpenAPI 3.0.3 JSON specification.
+
+## Installation
+
+```bash
+# With Claude support (default)
+pip install "openapi-generator[claude]"
+
+# With OpenAI support
+pip install "openapi-generator[openai]"
+
+# Both providers
+pip install "openapi-generator[all]"
+```
+
+## Usage
+
+```bash
+openapi-gen <path-to-project> --api-key <your-api-key>
+```
+
+The API key can also be provided via the `OPENAPI_GEN_API_KEY` environment variable:
+
+```bash
+export OPENAPI_GEN_API_KEY=sk-ant-...
+openapi-gen <path-to-project>
+```
+
+### Options
+
+| Option | Default | Description |
+|---|---|---|
+| `<path>` | _(required)_ | Path to the REST API project directory |
+| `--api-key` | `OPENAPI_GEN_API_KEY` env var | AI provider API key |
+| `--provider` | `claude` | AI provider: `claude` or `openai` |
+| `--output`, `-o` | `openapi.json` | Output file path |
+| `--title` | `API` | API title in the spec |
+| `--version` | `1.0.0` | API version in the spec |
+
+### Examples
+
+```bash
+# Generate a spec using Claude (default)
+export OPENAPI_GEN_API_KEY=sk-ant-...
+openapi-gen ./my-api
+
+# Generate a spec using OpenAI
+openapi-gen ./my-api --provider openai --api-key sk-...
+
+# Specify title, version, and output path
+openapi-gen ./my-api --title "My REST API" --version "2.0.0" --output ./docs/openapi.json
+```
+
+## Output
+
+The generated file follows the [OpenAPI 3.0.3 specification](https://spec.openapis.org/oas/v3.0.3) and can be used directly with tools like Swagger UI, Postman, or any OpenAPI-compatible client generator.
+
+## Supported Languages
+
+The tool scans files with the following extensions: `.py`, `.js`, `.ts`, `.go`, `.java`, `.rb`, `.php`, `.cs`
+
+## Development
+
+```bash
+git clone https://github.com/your-org/openapi-generator
+cd openapi-generator
+pip install -e ".[dev]"
+pytest
+```
+
+## License
+
+MIT

openapi_spec_generator-0.1.0/pyproject.toml

@@ -0,0 +1,29 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "openapi-spec-generator"
+version = "0.1.0"
+description = "Generate OpenAPI specifications for any REST API project directory."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+dependencies = [
+    "click>=8.0",
+]
+
+[project.optional-dependencies]
+claude = ["anthropic>=0.25"]
+openai = ["openai>=1.0"]
+all    = ["anthropic>=0.25", "openai>=1.0"]
+dev    = ["pytest>=8.0", "pytest-cov>=5.0"]
+
+[project.scripts]
+openapi-gen = "openapi_generator.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

openapi_spec_generator-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

openapi_spec_generator-0.1.0/src/openapi_generator/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

openapi_spec_generator-0.1.0/src/openapi_generator/ai_client.py

@@ -0,0 +1,22 @@
+def call_ai(prompt: str, api_key: str, provider: str) -> str:
+    if provider == "claude":
+        import anthropic
+
+        client = anthropic.Anthropic(api_key=api_key)
+        with client.messages.stream(
+            model="claude-sonnet-4-6",
+            max_tokens=4096,
+            messages=[{"role": "user", "content": prompt}],
+        ) as stream:
+            return stream.get_final_message().content[0].text
+    elif provider == "openai":
+        import openai
+
+        client = openai.OpenAI(api_key=api_key)
+        response = client.chat.completions.create(
+            model="gpt-4o",
+            messages=[{"role": "user", "content": prompt}],
+        )
+        return response.choices[0].message.content
+    else:
+        raise ValueError(f"Unknown provider '{provider}'. Choose 'claude' or 'openai'.")

openapi_spec_generator-0.1.0/src/openapi_generator/cli.py

@@ -0,0 +1,31 @@
+import json
+import click
+from pathlib import Path
+from .generator import generate_spec
+
+
+@click.command()
+@click.argument("path", type=click.Path(exists=True, file_okay=False, path_type=Path))
+@click.option("--output", "-o", default="openapi.json", show_default=True, help="Output file path.")
+@click.option("--title", default="API", show_default=True, help="API title.")
+@click.option("--version", "api_version", default="1.0.0", show_default=True, help="API version.")
+@click.option(
+    "--api-key",
+    envvar="OPENAPI_GEN_API_KEY",
+    required=True,
+    help="AI provider API key (or set OPENAPI_GEN_API_KEY).",
+)
+@click.option(
+    "--provider",
+    type=click.Choice(["claude", "openai"]),
+    default="claude",
+    show_default=True,
+    help="AI provider to use.",
+)
+def main(path: Path, output: str, title: str, api_version: str, api_key: str, provider: str) -> None:
+    """Generate an OpenAPI specification for a REST API project directory."""
+    click.echo(f"Scanning {path} ...")
+    spec = generate_spec(path, title=title, api_version=api_version, api_key=api_key, provider=provider)
+    output_path = Path(output)
+    output_path.write_text(json.dumps(spec, indent=2), encoding="utf-8")
+    click.echo(f"Wrote JSON spec to {output_path}")

openapi_spec_generator-0.1.0/src/openapi_generator/file_collector.py

@@ -0,0 +1,37 @@
+import os
+from pathlib import Path
+
+_INCLUDE_EXTENSIONS = {".py", ".js", ".ts", ".go", ".java", ".rb", ".php", ".cs"}
+_SKIP_DIRS = {"node_modules", ".git", "__pycache__", "venv", ".venv", "dist", "build", ".eggs"}
+
+
+def collect_files(project_dir: Path, max_bytes: int = 400_000) -> list[tuple[str, str]]:
+    """Walk *project_dir* and return (relative_path, content) for each source file.
+
+    Stops collecting once the total accumulated size exceeds *max_bytes* to
+    avoid exceeding AI model context limits.
+    """
+    results: list[tuple[str, str]] = []
+    total = 0
+
+    for root, dirs, files in os.walk(project_dir):
+        dirs[:] = [d for d in dirs if d not in _SKIP_DIRS]
+
+        for filename in sorted(files):
+            if Path(filename).suffix not in _INCLUDE_EXTENSIONS:
+                continue
+
+            abs_path = Path(root) / filename
+            try:
+                content = abs_path.read_text(encoding="utf-8")
+            except (UnicodeDecodeError, OSError):
+                continue
+
+            total += len(content.encode("utf-8"))
+            if total > max_bytes:
+                return results
+
+            rel_path = abs_path.relative_to(project_dir).as_posix()
+            results.append((rel_path, content))
+
+    return results

openapi_spec_generator-0.1.0/src/openapi_generator/generator.py

@@ -0,0 +1,49 @@
+import json
+import re
+from pathlib import Path
+
+from .file_collector import collect_files
+from .ai_client import call_ai
+
+_SYSTEM_PROMPT = (
+    "You are an expert OpenAPI specification writer. "
+    "Given source files from a REST API project, produce a complete, valid "
+    "OpenAPI 3.0.3 specification in JSON. "
+    "Respond with ONLY the raw JSON — no markdown fences, no explanation, no commentary."
+)
+
+
+def _build_prompt(files: list[tuple[str, str]], title: str, api_version: str) -> str:
+    file_blocks = "\n\n".join(
+        f"### {path}\n{content}" for path, content in files
+    )
+    return (
+        f"{_SYSTEM_PROMPT}\n\n"
+        f"API title: {title}\n"
+        f"API version: {api_version}\n\n"
+        f"Source files:\n\n{file_blocks}"
+    )
+
+
+def _parse_json(raw: str) -> dict:
+    text = raw.strip()
+    text = re.sub(r"^```(?:json)?\s*", "", text)
+    text = re.sub(r"\s*```$", "", text)
+    try:
+        return json.loads(text)
+    except json.JSONDecodeError as exc:
+        raise ValueError(f"AI response was not valid JSON:\n{raw[:500]}") from exc
+
+
+def generate_spec(
+    project_dir: Path,
+    *,
+    title: str = "API",
+    api_version: str = "1.0.0",
+    api_key: str,
+    provider: str = "claude",
+) -> dict:
+    files = collect_files(project_dir)
+    prompt = _build_prompt(files, title, api_version)
+    raw = call_ai(prompt, api_key, provider)
+    return _parse_json(raw)

openapi_spec_generator-0.1.0/src/openapi_spec_generator.egg-info/PKG-INFO

@@ -0,0 +1,98 @@
+Metadata-Version: 2.4
+Name: openapi-spec-generator
+Version: 0.1.0
+Summary: Generate OpenAPI specifications for any REST API project directory.
+License: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: click>=8.0
+Provides-Extra: claude
+Requires-Dist: anthropic>=0.25; extra == "claude"
+Provides-Extra: openai
+Requires-Dist: openai>=1.0; extra == "openai"
+Provides-Extra: all
+Requires-Dist: anthropic>=0.25; extra == "all"
+Requires-Dist: openai>=1.0; extra == "all"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-cov>=5.0; extra == "dev"
+
+# OpenAPI Generator
+
+A pip-installable CLI tool that uses AI to generate OpenAPI 3.0.3 specifications for any REST API project directory.
+
+## Overview
+
+Point this tool at any REST API project and it will scan the source files, send them to an AI model (Claude or OpenAI), and produce a valid OpenAPI 3.0.3 JSON specification.
+
+## Installation
+
+```bash
+# With Claude support (default)
+pip install "openapi-generator[claude]"
+
+# With OpenAI support
+pip install "openapi-generator[openai]"
+
+# Both providers
+pip install "openapi-generator[all]"
+```
+
+## Usage
+
+```bash
+openapi-gen <path-to-project> --api-key <your-api-key>
+```
+
+The API key can also be provided via the `OPENAPI_GEN_API_KEY` environment variable:
+
+```bash
+export OPENAPI_GEN_API_KEY=sk-ant-...
+openapi-gen <path-to-project>
+```
+
+### Options
+
+| Option | Default | Description |
+|---|---|---|
+| `<path>` | _(required)_ | Path to the REST API project directory |
+| `--api-key` | `OPENAPI_GEN_API_KEY` env var | AI provider API key |
+| `--provider` | `claude` | AI provider: `claude` or `openai` |
+| `--output`, `-o` | `openapi.json` | Output file path |
+| `--title` | `API` | API title in the spec |
+| `--version` | `1.0.0` | API version in the spec |
+
+### Examples
+
+```bash
+# Generate a spec using Claude (default)
+export OPENAPI_GEN_API_KEY=sk-ant-...
+openapi-gen ./my-api
+
+# Generate a spec using OpenAI
+openapi-gen ./my-api --provider openai --api-key sk-...
+
+# Specify title, version, and output path
+openapi-gen ./my-api --title "My REST API" --version "2.0.0" --output ./docs/openapi.json
+```
+
+## Output
+
+The generated file follows the [OpenAPI 3.0.3 specification](https://spec.openapis.org/oas/v3.0.3) and can be used directly with tools like Swagger UI, Postman, or any OpenAPI-compatible client generator.
+
+## Supported Languages
+
+The tool scans files with the following extensions: `.py`, `.js`, `.ts`, `.go`, `.java`, `.rb`, `.php`, `.cs`
+
+## Development
+
+```bash
+git clone https://github.com/your-org/openapi-generator
+cd openapi-generator
+pip install -e ".[dev]"
+pytest
+```
+
+## License
+
+MIT

openapi_spec_generator-0.1.0/src/openapi_spec_generator.egg-info/SOURCES.txt

@@ -0,0 +1,14 @@
+README.md
+pyproject.toml
+src/openapi_generator/__init__.py
+src/openapi_generator/ai_client.py
+src/openapi_generator/cli.py
+src/openapi_generator/file_collector.py
+src/openapi_generator/generator.py
+src/openapi_spec_generator.egg-info/PKG-INFO
+src/openapi_spec_generator.egg-info/SOURCES.txt
+src/openapi_spec_generator.egg-info/dependency_links.txt
+src/openapi_spec_generator.egg-info/entry_points.txt
+src/openapi_spec_generator.egg-info/requires.txt
+src/openapi_spec_generator.egg-info/top_level.txt
+tests/test_generator.py

openapi_spec_generator-0.1.0/src/openapi_spec_generator.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

openapi_spec_generator-0.1.0/src/openapi_spec_generator.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+openapi-gen = openapi_generator.cli:main

openapi_spec_generator-0.1.0/src/openapi_spec_generator.egg-info/requires.txt

@@ -0,0 +1,15 @@
+click>=8.0
+
+[all]
+anthropic>=0.25
+openai>=1.0
+
+[claude]
+anthropic>=0.25
+
+[dev]
+pytest>=8.0
+pytest-cov>=5.0
+
+[openai]
+openai>=1.0

openapi_spec_generator-0.1.0/src/openapi_spec_generator.egg-info/top_level.txt

@@ -0,0 +1 @@
+openapi_generator

openapi_spec_generator-0.1.0/tests/test_generator.py

@@ -0,0 +1,82 @@
+import json
+import pytest
+from pathlib import Path
+from unittest.mock import patch
+
+from openapi_generator.file_collector import collect_files
+from openapi_generator.generator import generate_spec
+
+
+# --- file_collector tests ---
+
+def test_collect_files_filters_extensions(tmp_path: Path) -> None:
+    (tmp_path / "app.py").write_text("# python")
+    (tmp_path / "README.md").write_text("# docs")
+    (tmp_path / "logo.png").write_bytes(b"\x89PNG")
+
+    files = collect_files(tmp_path)
+    paths = [p for p, _ in files]
+    assert "app.py" in paths
+    assert "README.md" not in paths
+    assert "logo.png" not in paths
+
+
+def test_collect_files_respects_max_bytes(tmp_path: Path) -> None:
+    # "a_small.py" sorts before "z_big.py", so small is collected first;
+    # adding big would exceed the budget, so we stop with exactly 1 file.
+    (tmp_path / "a_small.py").write_text("y" * 100)
+    (tmp_path / "z_big.py").write_text("x" * 300)
+
+    files = collect_files(tmp_path, max_bytes=250)
+    assert len(files) == 1
+    assert files[0][0] == "a_small.py"
+
+
+def test_collect_files_skips_excluded_dirs(tmp_path: Path) -> None:
+    node_modules = tmp_path / "node_modules"
+    node_modules.mkdir()
+    (node_modules / "dep.js").write_text("module.exports = {}")
+    (tmp_path / "index.js").write_text("const x = 1")
+
+    files = collect_files(tmp_path)
+    paths = [p for p, _ in files]
+    assert "index.js" in paths
+    assert not any("node_modules" in p for p in paths)
+
+
+# --- generator tests ---
+
+def test_generate_spec_calls_ai_and_parses_result(tmp_path: Path) -> None:
+    (tmp_path / "app.py").write_text("# flask app")
+    fake_spec = {
+        "openapi": "3.0.3",
+        "info": {"title": "Test API", "version": "0.1.0"},
+        "paths": {},
+    }
+
+    with patch("openapi_generator.generator.call_ai", return_value=json.dumps(fake_spec)):
+        spec = generate_spec(tmp_path, title="Test API", api_version="0.1.0", api_key="fake", provider="claude")
+
+    assert spec["openapi"] == "3.0.3"
+    assert spec["info"]["title"] == "Test API"
+    assert spec["info"]["version"] == "0.1.0"
+    assert "paths" in spec
+
+
+def test_generate_spec_strips_markdown_fences(tmp_path: Path) -> None:
+    (tmp_path / "app.py").write_text("# flask app")
+    fake_spec = {"openapi": "3.0.3", "info": {"title": "A", "version": "1"}, "paths": {}}
+    raw = f"```json\n{json.dumps(fake_spec)}\n```"
+
+    with patch("openapi_generator.generator.call_ai", return_value=raw):
+        spec = generate_spec(tmp_path, title="A", api_version="1", api_key="fake", provider="claude")
+
+    assert spec["openapi"] == "3.0.3"
+
+
+def test_generate_spec_raises_on_invalid_json(tmp_path: Path) -> None:
+    (tmp_path / "app.py").write_text("# flask app")
+
+    with patch("openapi_generator.generator.call_ai", return_value="not json at all"):
+        with pytest.raises(ValueError, match="not valid JSON"):
+            generate_spec(tmp_path, title="A", api_version="1", api_key="fake", provider="claude")