Add swagger-drogon generator
This commit is contained in:
gabdevele
@@ -0,0 +1,26 @@
|
||||
# swagger-drogon
|
||||
|
||||
`swagger-drogon` generates OpenAPI 3 documents from Drogon
|
||||
`HttpController` route macros.
|
||||
|
||||
The generator is intentionally hybrid:
|
||||
|
||||
- C++ route lists remain the source of truth for paths, methods and handlers.
|
||||
- Adjacent `openapi:` comment blocks provide operation metadata.
|
||||
- The generator infers simple path, query and JSON field usage from C++ code.
|
||||
- An app contract file provides schemas that cannot be safely inferred from
|
||||
dynamic `Json::Value` and SQL result rows.
|
||||
- Strict validation fails generation when an operation still has generic request
|
||||
or response bodies.
|
||||
|
||||
The contract file may be normal YAML when `PyYAML` is installed. Without
|
||||
external dependencies, the CLI also accepts JSON-compatible YAML, which is valid
|
||||
YAML syntax and keeps local CMake builds self-contained.
|
||||
|
||||
```bash
|
||||
python3 -m swagger_drogon generate \
|
||||
--controllers ../../controllers \
|
||||
--sources ../../controllers ../../services \
|
||||
--contract ../../docs/openapi/visione.yaml \
|
||||
--out /tmp/visione.openapi.json
|
||||
```
|
||||
@@ -0,0 +1,8 @@
|
||||
[project]
|
||||
name = "swagger-drogon"
|
||||
version = "0.1.0"
|
||||
requires-python = ">=3.11"
|
||||
dependencies = []
|
||||
|
||||
[project.scripts]
|
||||
swagger-drogon = "swagger_drogon.cli:main"
|
||||
@@ -0,0 +1,5 @@
|
||||
"""OpenAPI generator for Drogon HttpController route macros."""
|
||||
|
||||
from .generator import generate
|
||||
|
||||
__all__ = ["generate"]
|
||||
@@ -0,0 +1,4 @@
|
||||
from .cli import main
|
||||
|
||||
if __name__ == "__main__":
|
||||
main()
|
||||
@@ -0,0 +1,41 @@
|
||||
from __future__ import annotations
|
||||
|
||||
import argparse
|
||||
import json
|
||||
from pathlib import Path
|
||||
|
||||
from .contract import load_contract
|
||||
from .generator import generate
|
||||
|
||||
|
||||
def main() -> None:
|
||||
parser = argparse.ArgumentParser(prog="swagger-drogon")
|
||||
subparsers = parser.add_subparsers(dest="command")
|
||||
|
||||
generate_parser = subparsers.add_parser("generate")
|
||||
generate_parser.add_argument("--controllers", type=Path, required=True)
|
||||
generate_parser.add_argument("--sources", type=Path, nargs="*", default=[])
|
||||
generate_parser.add_argument("--contract", type=Path)
|
||||
generate_parser.add_argument("--out", type=Path, required=True)
|
||||
generate_parser.add_argument("--title", default="Drogon API")
|
||||
generate_parser.add_argument("--version", default="0.1.0")
|
||||
generate_parser.add_argument("--server", default="http://localhost:5555")
|
||||
|
||||
args = parser.parse_args()
|
||||
if args.command != "generate":
|
||||
parser.error("expected command: generate")
|
||||
|
||||
contract = load_contract(args.contract) if args.contract else {}
|
||||
spec = generate(
|
||||
controllers_dir=args.controllers,
|
||||
source_dirs=args.sources,
|
||||
contract=contract,
|
||||
title=args.title,
|
||||
version=args.version,
|
||||
server=args.server,
|
||||
)
|
||||
args.out.parent.mkdir(parents=True, exist_ok=True)
|
||||
args.out.write_text(
|
||||
json.dumps(spec, indent=2, sort_keys=True) + "\n",
|
||||
encoding="utf-8",
|
||||
)
|
||||
@@ -0,0 +1,22 @@
|
||||
from __future__ import annotations
|
||||
|
||||
import json
|
||||
from pathlib import Path
|
||||
from typing import Any
|
||||
|
||||
|
||||
def load_contract(path: Path) -> dict[str, Any]:
|
||||
text = path.read_text(encoding="utf-8")
|
||||
try:
|
||||
return json.loads(text)
|
||||
except json.JSONDecodeError:
|
||||
try:
|
||||
import yaml # type: ignore[import-untyped]
|
||||
except ImportError as error:
|
||||
raise ValueError(
|
||||
f"{path}: install PyYAML or use JSON-compatible YAML syntax"
|
||||
) from error
|
||||
data = yaml.safe_load(text)
|
||||
if not isinstance(data, dict):
|
||||
raise ValueError(f"{path}: contract root must be an object")
|
||||
return data
|
||||
@@ -0,0 +1,77 @@
|
||||
from __future__ import annotations
|
||||
|
||||
import re
|
||||
from pathlib import Path
|
||||
from typing import Any
|
||||
|
||||
from .infer import infer_operation, load_sources
|
||||
from .models import Route
|
||||
from .openapi import build_operation, build_path, merge_components
|
||||
from .parser import parse_routes
|
||||
from .validate import validate_spec
|
||||
|
||||
|
||||
def generate(
|
||||
controllers_dir: Path,
|
||||
source_dirs: list[Path],
|
||||
contract: dict[str, Any],
|
||||
title: str,
|
||||
version: str,
|
||||
server: str,
|
||||
) -> dict[str, Any]:
|
||||
sources = load_sources(source_dirs)
|
||||
spec: dict[str, Any] = {
|
||||
"openapi": "3.0.3",
|
||||
"info": {
|
||||
"title": title,
|
||||
"version": version,
|
||||
"description": contract.get(
|
||||
"description",
|
||||
"Generated from Drogon route macros, C++ metadata and schemas.",
|
||||
),
|
||||
},
|
||||
"servers": [{"url": server}],
|
||||
"components": merge_components(contract),
|
||||
"paths": {},
|
||||
}
|
||||
|
||||
operations_contract = contract.get("operations", {})
|
||||
if not isinstance(operations_contract, dict):
|
||||
raise ValueError("contract operations must be an object")
|
||||
|
||||
for route in parse_routes(controllers_dir):
|
||||
inferred = infer_operation(route, sources)
|
||||
path, path_params = build_path(route.raw_path, _handler_path_param_names(route))
|
||||
inferred.path_parameters = path_params
|
||||
operation_contract = operations_contract.get(route.operation_id, {})
|
||||
if not isinstance(operation_contract, dict):
|
||||
raise ValueError(f"{route.operation_id}: operation contract must be an object")
|
||||
operation = build_operation(route, inferred, operation_contract)
|
||||
spec["paths"].setdefault(path, {})[route.http_method] = operation
|
||||
|
||||
validate_spec(spec)
|
||||
return spec
|
||||
|
||||
|
||||
def _handler_path_param_names(route: Route) -> list[str]:
|
||||
text = route.header.read_text(encoding="utf-8")
|
||||
match = re.search(
|
||||
rf"void\s+{route.handler}\s*\((.*?)\)\s*;",
|
||||
text,
|
||||
re.MULTILINE | re.DOTALL,
|
||||
)
|
||||
if not match:
|
||||
return []
|
||||
params = match.group(1)
|
||||
names: list[str] = []
|
||||
for type_name, name in re.findall(r"\b(long long|int|size_t)\s+([A-Za-z_]\w*)", params):
|
||||
del type_name
|
||||
if name not in {"req"}:
|
||||
names.append(_openapi_param_name(name))
|
||||
return names
|
||||
|
||||
|
||||
def _openapi_param_name(name: str) -> str:
|
||||
if name.endswith("Id") and len(name) > 2:
|
||||
return "id" if name == "reportId" else name[:-2] + "_id"
|
||||
return name
|
||||
@@ -0,0 +1,163 @@
|
||||
from __future__ import annotations
|
||||
|
||||
import re
|
||||
from pathlib import Path
|
||||
from typing import Any
|
||||
|
||||
from .models import InferredOperation, Route
|
||||
|
||||
|
||||
def load_sources(source_dirs: list[Path]) -> dict[Path, str]:
|
||||
sources: dict[Path, str] = {}
|
||||
for directory in source_dirs:
|
||||
if not directory.exists():
|
||||
continue
|
||||
for path in sorted(directory.glob("*.cc")):
|
||||
sources[path] = path.read_text(encoding="utf-8")
|
||||
return sources
|
||||
|
||||
|
||||
def infer_operation(route: Route, sources: dict[Path, str]) -> InferredOperation:
|
||||
controller_body = _find_controller_body(route, sources)
|
||||
service_body = _find_service_body(controller_body, sources)
|
||||
combined = "\n".join(part for part in (controller_body, service_body) if part)
|
||||
|
||||
inferred = InferredOperation()
|
||||
inferred.query_parameters = _infer_query_parameters(controller_body)
|
||||
inferred.request_schema = _infer_request_schema(combined)
|
||||
inferred.response_schema = _infer_response_schema(combined)
|
||||
return inferred
|
||||
|
||||
|
||||
def _find_controller_body(route: Route, sources: dict[Path, str]) -> str:
|
||||
pattern = f"void {route.controller}::{route.handler}"
|
||||
for path, text in sources.items():
|
||||
if path.name != f"{route.controller}.cc":
|
||||
continue
|
||||
index = text.find(pattern)
|
||||
if index == -1:
|
||||
return ""
|
||||
brace = text.find("{", index)
|
||||
if brace == -1:
|
||||
return ""
|
||||
return _balanced_block(text, brace)
|
||||
return ""
|
||||
|
||||
|
||||
def _find_service_body(controller_body: str, sources: dict[Path, str]) -> str:
|
||||
match = re.search(r"\bservice\.([A-Za-z_]\w*)\s*\(", controller_body)
|
||||
if not match:
|
||||
return ""
|
||||
method = match.group(1)
|
||||
pattern = re.compile(rf"Json::Value\s+[A-Za-z_]\w*Service::{method}\s*\(")
|
||||
for path, text in sources.items():
|
||||
if not path.name.endswith("Service.cc"):
|
||||
continue
|
||||
match = pattern.search(text)
|
||||
if not match:
|
||||
continue
|
||||
brace = text.find("{", match.start())
|
||||
if brace == -1:
|
||||
return ""
|
||||
return _balanced_block(text, brace)
|
||||
return ""
|
||||
|
||||
|
||||
def _balanced_block(text: str, open_brace: int) -> str:
|
||||
depth = 0
|
||||
for index in range(open_brace, len(text)):
|
||||
char = text[index]
|
||||
if char == "{":
|
||||
depth += 1
|
||||
elif char == "}":
|
||||
depth -= 1
|
||||
if depth == 0:
|
||||
return text[open_brace + 1:index]
|
||||
return ""
|
||||
|
||||
|
||||
def _infer_query_parameters(controller_body: str) -> list[dict[str, Any]]:
|
||||
names = sorted(set(re.findall(r'queryValue\(\s*req\s*,\s*"([^"]+)"\s*\)', controller_body)))
|
||||
return [
|
||||
{
|
||||
"name": name,
|
||||
"in": "query",
|
||||
"required": False,
|
||||
"schema": _schema_for_field(name),
|
||||
}
|
||||
for name in names
|
||||
]
|
||||
|
||||
|
||||
def _infer_request_schema(text: str) -> dict[str, Any] | None:
|
||||
properties: dict[str, Any] = {}
|
||||
required: set[str] = set()
|
||||
|
||||
for group in re.findall(r"missingStrings\(\s*body\s*,\s*\{([^}]+)\}\s*\)", text):
|
||||
for field in re.findall(r'"([^"]+)"', group):
|
||||
properties[field] = {"type": "string"}
|
||||
required.add(field)
|
||||
|
||||
for field in re.findall(r'hasString\(\s*body\s*,\s*"([^"]+)"\s*\)', text):
|
||||
properties.setdefault(field, {"type": "string"})
|
||||
|
||||
for field in re.findall(r'hasNumber\(\s*body\s*,\s*"([^"]+)"\s*\)', text):
|
||||
properties.setdefault(field, _schema_for_field(field))
|
||||
required.add(field)
|
||||
|
||||
for field in re.findall(r'body\["([^"]+)"\]\.isBool\(\)', text):
|
||||
properties.setdefault(field, {"type": "boolean"})
|
||||
|
||||
for field in re.findall(r'body\["([^"]+)"\]\.isArray\(\)', text):
|
||||
properties.setdefault(field, {"type": "array", "items": {}})
|
||||
|
||||
for field in re.findall(r'body\["([^"]+)"\]\.isObject\(\)', text):
|
||||
properties.setdefault(field, {"type": "object", "additionalProperties": True})
|
||||
|
||||
for field in re.findall(r'body\.get\(\s*"([^"]+)"', text):
|
||||
properties.setdefault(field, {"type": "string"})
|
||||
|
||||
if not properties:
|
||||
return None
|
||||
|
||||
schema: dict[str, Any] = {
|
||||
"type": "object",
|
||||
"additionalProperties": False,
|
||||
"properties": properties,
|
||||
}
|
||||
if required:
|
||||
schema["required"] = sorted(required)
|
||||
return schema
|
||||
|
||||
|
||||
def _infer_response_schema(text: str) -> dict[str, Any] | None:
|
||||
properties: dict[str, Any] = {}
|
||||
if "success()" in text or 'body["ok"] = true' in text:
|
||||
properties["ok"] = {"type": "boolean"}
|
||||
for field in re.findall(r'response\["([^"]+)"\]', text):
|
||||
properties.setdefault(field, _schema_for_field(field))
|
||||
for field in re.findall(r'body\["([^"]+)"\]', text):
|
||||
properties.setdefault(field, _schema_for_field(field))
|
||||
if not properties:
|
||||
return None
|
||||
return {
|
||||
"type": "object",
|
||||
"additionalProperties": True,
|
||||
"properties": properties,
|
||||
}
|
||||
|
||||
|
||||
def _schema_for_field(name: str) -> dict[str, Any]:
|
||||
if name == "status":
|
||||
return {"type": "string"}
|
||||
if name == "id" or name.endswith("_id") or name.endswith("_hours") or name.endswith("_minutes"):
|
||||
return {"type": "integer", "format": "int64"}
|
||||
if name in {"latitude", "longitude", "rating", "points", "total", "value"}:
|
||||
return {"type": "number"}
|
||||
if name.startswith("is_") or name in {"ok", "banned", "must_change_password"}:
|
||||
return {"type": "boolean"}
|
||||
if name.endswith("s") or name in {"roles", "permissions", "reports", "messages", "media"}:
|
||||
return {"type": "array", "items": {"type": "object", "additionalProperties": True}}
|
||||
if name.endswith("_geojson") or name in {"user", "report"}:
|
||||
return {"type": "object", "additionalProperties": True}
|
||||
return {"type": "string"}
|
||||
@@ -0,0 +1,27 @@
|
||||
from __future__ import annotations
|
||||
|
||||
from dataclasses import dataclass, field
|
||||
from pathlib import Path
|
||||
from typing import Any
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class Route:
|
||||
controller: str
|
||||
handler: str
|
||||
raw_path: str
|
||||
http_method: str
|
||||
metadata: dict[str, str]
|
||||
header: Path
|
||||
|
||||
@property
|
||||
def operation_id(self) -> str:
|
||||
return f"{self.controller}.{self.handler}"
|
||||
|
||||
|
||||
@dataclass
|
||||
class InferredOperation:
|
||||
path_parameters: list[dict[str, Any]] = field(default_factory=list)
|
||||
query_parameters: list[dict[str, Any]] = field(default_factory=list)
|
||||
request_schema: dict[str, Any] | None = None
|
||||
response_schema: dict[str, Any] | None = None
|
||||
@@ -0,0 +1,163 @@
|
||||
from __future__ import annotations
|
||||
|
||||
import copy
|
||||
import re
|
||||
from typing import Any
|
||||
|
||||
from .models import InferredOperation, Route
|
||||
from .parser import parse_tags
|
||||
|
||||
|
||||
METHODS_WITH_JSON_BODY = {"post", "put", "patch"}
|
||||
|
||||
|
||||
def build_path(raw_path: str, names: list[str] | None = None) -> tuple[str, list[dict[str, Any]]]:
|
||||
parameters: list[dict[str, Any]] = []
|
||||
names = names or []
|
||||
|
||||
def replace(match: re.Match[str]) -> str:
|
||||
index = int(match.group(1)) - 1
|
||||
name = names[index] if index < len(names) else ("id" if index == 0 else f"param{index + 1}")
|
||||
parameters.append(
|
||||
{
|
||||
"name": name,
|
||||
"in": "path",
|
||||
"required": True,
|
||||
"schema": {"type": "integer", "format": "int64"},
|
||||
}
|
||||
)
|
||||
return "{" + name + "}"
|
||||
|
||||
return re.sub(r"\{(\d+)\}", replace, raw_path), parameters
|
||||
|
||||
|
||||
def build_operation(
|
||||
route: Route,
|
||||
inferred: InferredOperation,
|
||||
operation_contract: dict[str, Any],
|
||||
) -> dict[str, Any]:
|
||||
metadata = route.metadata
|
||||
response_schema = _schema_from_contract(operation_contract, "response")
|
||||
if response_schema is None:
|
||||
response_schema = inferred.response_schema
|
||||
|
||||
op: dict[str, Any] = {
|
||||
"tags": parse_tags(metadata["tags"]),
|
||||
"operationId": route.operation_id,
|
||||
"summary": metadata["summary"],
|
||||
"description": metadata["description"],
|
||||
"parameters": [*inferred.path_parameters, *inferred.query_parameters],
|
||||
"responses": _responses(metadata["response"], response_schema, operation_contract),
|
||||
}
|
||||
|
||||
request_body = _request_body(route, inferred, operation_contract)
|
||||
if request_body is not None:
|
||||
op["requestBody"] = request_body
|
||||
|
||||
if metadata["auth"] == "bearer":
|
||||
op["security"] = [{"bearerAuth": []}]
|
||||
elif metadata["auth"] != "public":
|
||||
raise ValueError(f"{route.header}: unsupported auth kind: {metadata['auth']}")
|
||||
|
||||
return op
|
||||
|
||||
|
||||
def merge_components(contract: dict[str, Any]) -> dict[str, Any]:
|
||||
components = copy.deepcopy(contract.get("components", {}))
|
||||
components.setdefault("securitySchemes", {})
|
||||
components["securitySchemes"].setdefault(
|
||||
"bearerAuth", {"type": "http", "scheme": "bearer"}
|
||||
)
|
||||
return components
|
||||
|
||||
|
||||
def _request_body(
|
||||
route: Route,
|
||||
inferred: InferredOperation,
|
||||
operation_contract: dict[str, Any],
|
||||
) -> dict[str, Any] | None:
|
||||
body_kind = route.metadata["body"]
|
||||
if body_kind == "none":
|
||||
return None
|
||||
|
||||
explicit = operation_contract.get("requestBody")
|
||||
if explicit is not None:
|
||||
return copy.deepcopy(explicit)
|
||||
|
||||
schema = _schema_from_contract(operation_contract, "request")
|
||||
if schema is None:
|
||||
schema = inferred.request_schema
|
||||
|
||||
if body_kind == "multipart":
|
||||
if schema is None:
|
||||
schema = {
|
||||
"type": "object",
|
||||
"required": ["files"],
|
||||
"properties": {
|
||||
"files": {
|
||||
"type": "array",
|
||||
"items": {"type": "string", "format": "binary"},
|
||||
}
|
||||
},
|
||||
}
|
||||
return {
|
||||
"required": True,
|
||||
"content": {"multipart/form-data": {"schema": schema}},
|
||||
}
|
||||
|
||||
if body_kind == "json" and route.http_method in METHODS_WITH_JSON_BODY:
|
||||
return {
|
||||
"required": True,
|
||||
"content": {"application/json": {"schema": schema or {"type": "object"}}},
|
||||
}
|
||||
|
||||
raise ValueError(
|
||||
f"{route.header}: unsupported body kind {body_kind} for {route.http_method.upper()}"
|
||||
)
|
||||
|
||||
|
||||
def _responses(
|
||||
description: str,
|
||||
response_schema: dict[str, Any] | None,
|
||||
operation_contract: dict[str, Any],
|
||||
) -> dict[str, Any]:
|
||||
if "responses" in operation_contract:
|
||||
return copy.deepcopy(operation_contract["responses"])
|
||||
|
||||
content_type = operation_contract.get("responseContentType", "application/json")
|
||||
if content_type == "text/html":
|
||||
success = {
|
||||
"description": description,
|
||||
"content": {"text/html": {"schema": {"type": "string"}}},
|
||||
}
|
||||
else:
|
||||
success = {
|
||||
"description": description,
|
||||
"content": {
|
||||
content_type: {
|
||||
"schema": response_schema or {"type": "object"},
|
||||
}
|
||||
},
|
||||
}
|
||||
|
||||
responses: dict[str, Any] = {"200": success}
|
||||
if operation_contract.get("created", False):
|
||||
responses = {"201": success}
|
||||
|
||||
for status, response in operation_contract.get("errors", {}).items():
|
||||
responses[str(status)] = copy.deepcopy(response)
|
||||
return responses
|
||||
|
||||
|
||||
def _schema_from_contract(
|
||||
operation_contract: dict[str, Any],
|
||||
key: str,
|
||||
) -> dict[str, Any] | None:
|
||||
value = operation_contract.get(key)
|
||||
if value is None:
|
||||
return None
|
||||
if isinstance(value, str):
|
||||
return {"$ref": value}
|
||||
if isinstance(value, dict):
|
||||
return copy.deepcopy(value)
|
||||
raise ValueError(f"operation contract field {key} must be string or object")
|
||||
@@ -0,0 +1,75 @@
|
||||
from __future__ import annotations
|
||||
|
||||
import re
|
||||
from pathlib import Path
|
||||
|
||||
from .models import Route
|
||||
|
||||
|
||||
ROUTE_RE = re.compile(
|
||||
r"ADD_METHOD_TO\(\s*([A-Za-z_]\w*)::([A-Za-z_]\w*)\s*,\s*"
|
||||
r'"([^"]+)"\s*,\s*drogon::([A-Za-z]+)\s*\)',
|
||||
re.MULTILINE | re.DOTALL,
|
||||
)
|
||||
|
||||
REQUIRED_METADATA = {"tags", "summary", "description", "auth", "body", "response"}
|
||||
|
||||
|
||||
def parse_metadata(header: Path, text: str, route_start: int) -> dict[str, str]:
|
||||
prefix = text[:route_start].rstrip()
|
||||
if not prefix.endswith("*/"):
|
||||
raise ValueError(f"{header}: route is missing an openapi metadata block")
|
||||
|
||||
comment_start = prefix.rfind("/*")
|
||||
if comment_start == -1:
|
||||
raise ValueError(f"{header}: route is missing an openapi metadata block")
|
||||
|
||||
block = prefix[comment_start + 2:-2]
|
||||
metadata: dict[str, str] = {}
|
||||
in_openapi_block = False
|
||||
|
||||
for raw_line in block.splitlines():
|
||||
line = raw_line.strip()
|
||||
if line.startswith("*"):
|
||||
line = line[1:].strip()
|
||||
if not line:
|
||||
continue
|
||||
if line == "openapi:":
|
||||
in_openapi_block = True
|
||||
continue
|
||||
if not in_openapi_block:
|
||||
continue
|
||||
|
||||
match = re.match(r"([A-Za-z_]+):\s*(.+)", line)
|
||||
if match:
|
||||
metadata[match.group(1)] = match.group(2).strip()
|
||||
|
||||
missing = sorted(REQUIRED_METADATA - metadata.keys())
|
||||
if missing:
|
||||
names = ", ".join(missing)
|
||||
raise ValueError(f"{header}: openapi metadata block is missing: {names}")
|
||||
|
||||
return metadata
|
||||
|
||||
|
||||
def parse_routes(controllers_dir: Path) -> list[Route]:
|
||||
routes: list[Route] = []
|
||||
for header in sorted(controllers_dir.glob("*.h")):
|
||||
text = header.read_text(encoding="utf-8")
|
||||
for match in ROUTE_RE.finditer(text):
|
||||
controller, handler, raw_path, drogon_method = match.groups()
|
||||
routes.append(
|
||||
Route(
|
||||
controller=controller,
|
||||
handler=handler,
|
||||
raw_path=raw_path,
|
||||
http_method=drogon_method.lower(),
|
||||
metadata=parse_metadata(header, text, match.start()),
|
||||
header=header,
|
||||
)
|
||||
)
|
||||
return routes
|
||||
|
||||
|
||||
def parse_tags(value: str) -> list[str]:
|
||||
return [tag.strip() for tag in value.split(",") if tag.strip()]
|
||||
@@ -0,0 +1,99 @@
|
||||
from __future__ import annotations
|
||||
|
||||
from typing import Any
|
||||
|
||||
|
||||
def validate_spec(spec: dict[str, Any]) -> None:
|
||||
_validate_no_photos(spec)
|
||||
_validate_refs(spec)
|
||||
_validate_operations(spec)
|
||||
|
||||
|
||||
def _validate_no_photos(spec: dict[str, Any]) -> None:
|
||||
for path in spec.get("paths", {}):
|
||||
if "/photos" in path:
|
||||
raise ValueError(f"generated OpenAPI path still uses /photos: {path}")
|
||||
|
||||
|
||||
def _validate_refs(spec: dict[str, Any]) -> None:
|
||||
for ref in _walk_refs(spec):
|
||||
_resolve_ref(spec, ref)
|
||||
|
||||
|
||||
def _validate_operations(spec: dict[str, Any]) -> None:
|
||||
for path, path_item in spec.get("paths", {}).items():
|
||||
for method, operation in path_item.items():
|
||||
label = f"{method.upper()} {path}"
|
||||
if method.lower() == "get" and "requestBody" in operation:
|
||||
raise ValueError(f"{label}: GET operation must not have requestBody")
|
||||
|
||||
request_body = operation.get("requestBody")
|
||||
if request_body is not None:
|
||||
for schema in _content_schemas(request_body):
|
||||
if _is_generic_object(spec, schema):
|
||||
raise ValueError(f"{label}: request schema is generic object")
|
||||
|
||||
success = _success_response(operation)
|
||||
if success is None:
|
||||
raise ValueError(f"{label}: missing 2xx response")
|
||||
for schema in _content_schemas(success):
|
||||
if _is_generic_object(spec, schema):
|
||||
raise ValueError(f"{label}: response schema is generic object")
|
||||
|
||||
|
||||
def _success_response(operation: dict[str, Any]) -> dict[str, Any] | None:
|
||||
for status in sorted(operation.get("responses", {})):
|
||||
if str(status).startswith("2"):
|
||||
return operation["responses"][status]
|
||||
return None
|
||||
|
||||
|
||||
def _content_schemas(container: dict[str, Any]) -> list[dict[str, Any]]:
|
||||
schemas: list[dict[str, Any]] = []
|
||||
for media in container.get("content", {}).values():
|
||||
schema = media.get("schema")
|
||||
if isinstance(schema, dict):
|
||||
schemas.append(schema)
|
||||
return schemas
|
||||
|
||||
|
||||
def _is_generic_object(spec: dict[str, Any], schema: dict[str, Any]) -> bool:
|
||||
resolved = _resolve_schema(spec, schema)
|
||||
if resolved.get("type") != "object":
|
||||
return False
|
||||
meaningful = {"properties", "additionalProperties", "oneOf", "anyOf", "allOf"}
|
||||
return not any(key in resolved for key in meaningful)
|
||||
|
||||
|
||||
def _resolve_schema(spec: dict[str, Any], schema: dict[str, Any]) -> dict[str, Any]:
|
||||
if "$ref" not in schema:
|
||||
return schema
|
||||
resolved = _resolve_ref(spec, schema["$ref"])
|
||||
if not isinstance(resolved, dict):
|
||||
raise ValueError(f"{schema['$ref']}: does not resolve to an object")
|
||||
return resolved
|
||||
|
||||
|
||||
def _resolve_ref(spec: dict[str, Any], ref: str) -> Any:
|
||||
if not ref.startswith("#/"):
|
||||
raise ValueError(f"external refs are not supported: {ref}")
|
||||
current: Any = spec
|
||||
for part in ref[2:].split("/"):
|
||||
if not isinstance(current, dict) or part not in current:
|
||||
raise ValueError(f"unresolved OpenAPI ref: {ref}")
|
||||
current = current[part]
|
||||
return current
|
||||
|
||||
|
||||
def _walk_refs(value: Any) -> list[str]:
|
||||
refs: list[str] = []
|
||||
if isinstance(value, dict):
|
||||
ref = value.get("$ref")
|
||||
if isinstance(ref, str):
|
||||
refs.append(ref)
|
||||
for child in value.values():
|
||||
refs.extend(_walk_refs(child))
|
||||
elif isinstance(value, list):
|
||||
for child in value:
|
||||
refs.extend(_walk_refs(child))
|
||||
return refs
|
||||
@@ -0,0 +1,170 @@
|
||||
from __future__ import annotations
|
||||
|
||||
import json
|
||||
import sys
|
||||
import tempfile
|
||||
import unittest
|
||||
from pathlib import Path
|
||||
|
||||
sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
|
||||
|
||||
from swagger_drogon.contract import load_contract
|
||||
from swagger_drogon.generator import generate
|
||||
from swagger_drogon.infer import infer_operation, load_sources
|
||||
from swagger_drogon.parser import parse_routes
|
||||
|
||||
|
||||
class SwaggerDrogonTest(unittest.TestCase):
|
||||
def test_parse_route_metadata(self) -> None:
|
||||
with tempfile.TemporaryDirectory() as tmp:
|
||||
root = Path(tmp)
|
||||
controllers = root / "controllers"
|
||||
controllers.mkdir()
|
||||
(controllers / "SampleController.h").write_text(
|
||||
"""
|
||||
class SampleController {
|
||||
METHOD_LIST_BEGIN
|
||||
/*
|
||||
* openapi:
|
||||
* tags: Sample
|
||||
* summary: List samples
|
||||
* description: Lists samples.
|
||||
* auth: public
|
||||
* body: none
|
||||
* response: Sample list.
|
||||
*/
|
||||
ADD_METHOD_TO(SampleController::list, "/api/v1/samples", drogon::Get);
|
||||
METHOD_LIST_END
|
||||
};
|
||||
""",
|
||||
encoding="utf-8",
|
||||
)
|
||||
routes = parse_routes(controllers)
|
||||
self.assertEqual(len(routes), 1)
|
||||
self.assertEqual(routes[0].operation_id, "SampleController.list")
|
||||
self.assertEqual(routes[0].metadata["summary"], "List samples")
|
||||
|
||||
def test_infer_query_and_json_fields(self) -> None:
|
||||
with tempfile.TemporaryDirectory() as tmp:
|
||||
root = Path(tmp)
|
||||
controllers = root / "controllers"
|
||||
services = root / "services"
|
||||
controllers.mkdir()
|
||||
services.mkdir()
|
||||
header = controllers / "SampleController.h"
|
||||
header.write_text(
|
||||
"""
|
||||
class SampleController {
|
||||
METHOD_LIST_BEGIN
|
||||
/*
|
||||
* openapi:
|
||||
* tags: Sample
|
||||
* summary: Create sample
|
||||
* description: Creates a sample.
|
||||
* auth: bearer
|
||||
* body: json
|
||||
* response: Created sample.
|
||||
*/
|
||||
ADD_METHOD_TO(SampleController::create, "/api/v1/samples", drogon::Post);
|
||||
METHOD_LIST_END
|
||||
};
|
||||
""",
|
||||
encoding="utf-8",
|
||||
)
|
||||
(controllers / "SampleController.cc").write_text(
|
||||
"""
|
||||
void SampleController::create(const drogon::HttpRequestPtr &req) {
|
||||
auto status = queryValue(req, "status");
|
||||
SampleService service;
|
||||
service.create(body);
|
||||
}
|
||||
""",
|
||||
encoding="utf-8",
|
||||
)
|
||||
(services / "SampleService.cc").write_text(
|
||||
"""
|
||||
Json::Value SampleService::create(const Json::Value &body) {
|
||||
const auto missing = validation::missingStrings(body, {"name"});
|
||||
if (!validation::hasNumber(body, "category_id")) {}
|
||||
auto response = success();
|
||||
response["sample_id"] = Json::Int64(1);
|
||||
return response;
|
||||
}
|
||||
""",
|
||||
encoding="utf-8",
|
||||
)
|
||||
route = parse_routes(controllers)[0]
|
||||
inferred = infer_operation(route, load_sources([controllers, services]))
|
||||
self.assertEqual(inferred.query_parameters[0]["name"], "status")
|
||||
self.assertIn("name", inferred.request_schema["required"])
|
||||
self.assertIn("category_id", inferred.request_schema["required"])
|
||||
self.assertIn("sample_id", inferred.response_schema["properties"])
|
||||
|
||||
def test_strict_validation_rejects_generic_contract(self) -> None:
|
||||
with tempfile.TemporaryDirectory() as tmp:
|
||||
root = Path(tmp)
|
||||
controllers = root / "controllers"
|
||||
controllers.mkdir()
|
||||
(controllers / "SampleController.h").write_text(
|
||||
"""
|
||||
class SampleController {
|
||||
METHOD_LIST_BEGIN
|
||||
/*
|
||||
* openapi:
|
||||
* tags: Sample
|
||||
* summary: Create sample
|
||||
* description: Creates a sample.
|
||||
* auth: public
|
||||
* body: json
|
||||
* response: Created sample.
|
||||
*/
|
||||
ADD_METHOD_TO(SampleController::create, "/api/v1/samples", drogon::Post);
|
||||
METHOD_LIST_END
|
||||
};
|
||||
""",
|
||||
encoding="utf-8",
|
||||
)
|
||||
with self.assertRaisesRegex(ValueError, "generic object"):
|
||||
generate(
|
||||
controllers_dir=controllers,
|
||||
source_dirs=[],
|
||||
contract={
|
||||
"operations": {
|
||||
"SampleController.create": {
|
||||
"request": {"type": "object"},
|
||||
"response": {"type": "object"},
|
||||
}
|
||||
}
|
||||
},
|
||||
title="Sample",
|
||||
version="0.1.0",
|
||||
server="http://localhost",
|
||||
)
|
||||
|
||||
def test_visione_contract_generates_concrete_media_path(self) -> None:
|
||||
repo = Path(__file__).resolve().parents[3]
|
||||
spec = generate(
|
||||
controllers_dir=repo / "controllers",
|
||||
source_dirs=[repo / "controllers", repo / "services"],
|
||||
contract=load_contract(repo / "docs/openapi/visione.yaml"),
|
||||
title="Visione API",
|
||||
version="0.1.0",
|
||||
server="http://localhost:5555",
|
||||
)
|
||||
self.assertIn("/api/v1/reports/{id}/media", spec["paths"])
|
||||
self.assertFalse(any("/photos" in path for path in spec["paths"]))
|
||||
for path, path_item in spec["paths"].items():
|
||||
for method, operation in path_item.items():
|
||||
if method == "get":
|
||||
self.assertNotIn("requestBody", operation, path)
|
||||
success = next(
|
||||
response
|
||||
for status, response in operation["responses"].items()
|
||||
if str(status).startswith("2")
|
||||
)
|
||||
self.assertTrue(success.get("content"), operation["operationId"])
|
||||
json.dumps(spec)
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
unittest.main()
|
||||
Reference in New Issue
Block a user