Build Agentic workflows, RAG pipelines, with rich AI model and tool support on one collaborative workspace. Deploy on cloud, VPC, or self-hosted, so teams move from prototype to production without rebuilding the stack.
Python agentagentic-aiagentic-frameworkagentic-workflowaiautomationclaudedeepseekgenaigptllmlow-codemcpnextjsno-codeopenaipythonskillsworkflow
"""Unit tests for the Markdown API docs generator."""
import importlib.util
import json
import subprocess
import sys
from pathlib import Path
from types import ModuleType
import pytest
def _load_generate_swagger_markdown_docs_module() -> ModuleType:
api_dir = Path(__file__).resolve().parents[3]
script_path = api_dir / "dev" / "generate_swagger_markdown_docs.py"
spec = importlib.util.spec_from_file_location("generate_swagger_markdown_docs", script_path)
assert spec
assert spec.loader
module = importlib.util.module_from_spec(spec)
sys.modules[spec.name] = module
spec.loader.exec_module(module) # type: ignore[attr-defined]
return module
def test_generate_markdown_docs_keeps_split_docs_and_merges_fastopenapi_into_console(
tmp_path: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
module = _load_generate_swagger_markdown_docs_module()
openapi_dir = tmp_path / "openapi"
markdown_dir = tmp_path / "markdown"
stale_combined_doc = markdown_dir / "api-reference.md"
markdown_dir.mkdir()
stale_combined_doc.write_text("stale", encoding="utf-8")
def write_specs(output_dir: Path) -> list[Path]:
output_dir.mkdir(parents=True, exist_ok=True)
paths = []
for target in module.SPEC_TARGETS:
path = output_dir / target.filename
path.write_text("{}", encoding="utf-8")
paths.append(path)
return paths
def write_fastopenapi_specs(output_dir: Path) -> list[Path]:
output_dir.mkdir(parents=True, exist_ok=True)
path = output_dir / module.FASTOPENAPI_SPEC_TARGETS[0].filename
path.write_text("{}", encoding="utf-8")
return [path]
def convert_spec_to_markdown(spec_path: Path, markdown_path: Path) -> None:
markdown_path.write_text(f"# {spec_path.stem}\n\n## Routes\n", encoding="utf-8")
monkeypatch.setattr(module, "generate_specs", write_specs)
monkeypatch.setattr(module, "generate_fastopenapi_specs", write_fastopenapi_specs)
monkeypatch.setattr(module, "_convert_spec_to_markdown", convert_spec_to_markdown)
written_paths = module.generate_markdown_docs(openapi_dir, markdown_dir)
assert [path.name for path in written_paths] == [
"console-openapi.md",
"web-openapi.md",
"service-openapi.md",
"openapi-openapi.md",
]
assert not stale_combined_doc.exists()
assert not list(openapi_dir.glob("*.json"))
console_markdown = (markdown_dir / "console-openapi.md").read_text(encoding="utf-8")
assert "## FastOpenAPI Preview (OpenAPI 3.1)" in console_markdown
assert "### fastopenapi-console-openapi" in console_markdown
assert "#### Routes" in console_markdown
assert "FastOpenAPI Preview" not in (markdown_dir / "web-openapi.md").read_text(encoding="utf-8")
assert "FastOpenAPI Preview" not in (markdown_dir / "service-openapi.md").read_text(encoding="utf-8")
def test_generate_markdown_docs_only_removes_generated_specs_from_separate_swagger_dir(
tmp_path: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
module = _load_generate_swagger_markdown_docs_module()
swagger_dir = tmp_path / "swagger"
markdown_dir = tmp_path / "markdown"
swagger_dir.mkdir()
existing_file = swagger_dir / "existing.txt"
existing_file.write_text("keep me", encoding="utf-8")
def write_specs(output_dir: Path) -> list[Path]:
output_dir.mkdir(parents=True, exist_ok=True)
paths = []
for target in module.SPEC_TARGETS:
path = output_dir / target.filename
path.write_text("{}", encoding="utf-8")
paths.append(path)
return paths
def write_fastopenapi_specs(output_dir: Path) -> list[Path]:
output_dir.mkdir(parents=True, exist_ok=True)
path = output_dir / module.FASTOPENAPI_SPEC_TARGETS[0].filename
path.write_text("{}", encoding="utf-8")
return [path]
def convert_spec_to_markdown(spec_path: Path, markdown_path: Path) -> None:
markdown_path.write_text(f"# {spec_path.stem}\n", encoding="utf-8")
monkeypatch.setattr(module, "generate_specs", write_specs)
monkeypatch.setattr(module, "generate_fastopenapi_specs", write_fastopenapi_specs)
monkeypatch.setattr(module, "_convert_spec_to_markdown", convert_spec_to_markdown)
module.generate_markdown_docs(swagger_dir, markdown_dir)
assert existing_file.read_text(encoding="utf-8") == "keep me"
assert not list(swagger_dir.glob("*.json"))
def test_patch_union_schema_markdown_fills_converter_blank_schema_types(tmp_path: Path) -> None:
module = _load_generate_swagger_markdown_docs_module()
spec_path = tmp_path / "console-openapi.json"
spec_path.write_text(
json.dumps(
{
"components": {
"schemas": {
"FormInputConfig": {
"oneOf": [
{"$ref": "#/components/schemas/ParagraphInputConfig"},
{"$ref": "#/components/schemas/SelectInputConfig"},
{"$ref": "#/components/schemas/FileInputConfig"},
],
},
"ParagraphInputConfig": {
"properties": {
"default": {
"anyOf": [
{"$ref": "#/components/schemas/StringSource"},
{"type": "null"},
],
"default": None,
},
"output_variable_name": {"type": "string"},
},
},
"SelectInputConfig": {
"properties": {
"option_source": {"$ref": "#/components/schemas/StringListSource"},
},
},
"FileInputConfig": {
"properties": {
"allowed_file_types": {
"type": "array",
"items": {"$ref": "#/components/schemas/FileType"},
},
},
},
},
}
}
),
encoding="utf-8",
)
markdown = """#### FormInputConfig
| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| FormInputConfig | | | |
#### ParagraphInputConfig
| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| default | | | No |
| output_variable_name | string | | Yes |
#### SelectInputConfig
| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| option_source | | | Yes |
#### FileInputConfig
| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| allowed_file_types | | | No |
"""
patched = module._patch_union_schema_markdown(markdown, spec_path)
assert (
"| FormInputConfig | "
"[ParagraphInputConfig](#paragraphinputconfig)<br>"
"[SelectInputConfig](#selectinputconfig)<br>"
"[FileInputConfig](#fileinputconfig) | | |"
) in patched
assert "| default | [StringSource](#stringsource) | | No |" in patched
assert "| output_variable_name | string | | Yes |" in patched
assert "| option_source | [StringListSource](#stringlistsource) | | Yes |" in patched
assert "| allowed_file_types | [ [FileType](#filetype) ] | | No |" in patched
def test_patch_union_schema_markdown_fills_regular_schema_union_property(tmp_path: Path) -> None:
module = _load_generate_swagger_markdown_docs_module()
spec_path = tmp_path / "service-openapi.json"
spec_path.write_text(
json.dumps(
{
"components": {
"schemas": {
"DocumentMetadataResponse": {
"properties": {
"id": {"type": "string"},
"value": {
"anyOf": [
{"type": "string"},
{"type": "integer"},
{"type": "number"},
{"type": "boolean"},
{"type": "null"},
],
},
},
},
},
}
}
),
encoding="utf-8",
)
markdown = """#### DocumentMetadataResponse
| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| id | string | | Yes |
| value | string | | No |
"""
patched = module._patch_union_schema_markdown(markdown, spec_path)
assert "| value | string<br>integer<br>number<br>boolean | | No |" in patched
def test_patch_union_schema_markdown_preserves_nullable_enum_values(tmp_path: Path) -> None:
module = _load_generate_swagger_markdown_docs_module()
spec_path = tmp_path / "console-openapi.json"
spec_path.write_text(
json.dumps(
{
"components": {
"schemas": {
"StepByStepTourStatePatchPayload": {
"properties": {
"task_id": {
"anyOf": [
{"enum": ["home", "studio"], "type": "string"},
{"type": "null"},
],
},
},
},
},
}
}
),
encoding="utf-8",
)
markdown = """#### StepByStepTourStatePatchPayload
| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| task_id | string | Task ID | No |
"""
patched = module._patch_union_schema_markdown(markdown, spec_path)
assert '| task_id | string, <br>**Available values:** "home", "studio" | Task ID | No |' in patched
def test_patch_union_schema_markdown_fills_array_item_union_property(tmp_path: Path) -> None:
module = _load_generate_swagger_markdown_docs_module()
spec_path = tmp_path / "console-openapi.json"
spec_path.write_text(
json.dumps(
{
"components": {
"schemas": {
"MemberInviteResponse": {
"properties": {
"invitation_results": {
"type": "array",
"items": {
"oneOf": [
{"$ref": "#/components/schemas/MemberInviteSuccessResponse"},
{"$ref": "#/components/schemas/MemberInviteAlreadyMemberResponse"},
{"$ref": "#/components/schemas/MemberInviteFailedResponse"},
],
},
},
},
},
},
}
}
),
encoding="utf-8",
)
markdown = """#### MemberInviteResponse
| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| invitation_results | [ ] | | Yes |
"""
patched = module._patch_union_schema_markdown(markdown, spec_path)
assert (
"| invitation_results | [ "
"[MemberInviteSuccessResponse](#memberinvitesuccessresponse)<br>"
"[MemberInviteAlreadyMemberResponse](#memberinvitealreadymemberresponse)<br>"
"[MemberInviteFailedResponse](#memberinvitefailedresponse) ] | | Yes |"
) in patched
def test_patch_union_schema_markdown_ignores_specs_without_schemas(tmp_path: Path) -> None:
module = _load_generate_swagger_markdown_docs_module()
spec_path = tmp_path / "console-openapi.json"
spec_path.write_text("{}", encoding="utf-8")
assert module._patch_union_schema_markdown("unchanged", spec_path) == "unchanged"
def test_patch_union_response_markdown_fills_converter_blank_error_bodies(tmp_path: Path) -> None:
module = _load_generate_swagger_markdown_docs_module()
spec_path = tmp_path / "console-openapi.json"
spec_path.write_text(
json.dumps(
{
"paths": {
"/plugins/{category}/list": {
"get": {
"responses": {
"200": {"content": {"application/json": {"schema": {"type": "object"}}}},
"400": {
"content": {
"application/json": {
"schema": {
"anyOf": [
{"$ref": "#/components/schemas/PluginError"},
{"$ref": "#/components/schemas/ErrorResponse"},
]
}
}
}
},
"default": {
"content": {
"application/json": {"schema": {"$ref": "#/components/schemas/ErrorResponse"}}
}
},
}
}
}
}
}
),
encoding="utf-8",
)
markdown = """### ~~[GET] /plugins/{category}/list~~
#### Responses
| Code | Description | Schema |
| ---- | ----------- | ------ |
| 200 | Success | **application/json**: object<br> |
| 400 | Bad \\| Request | **application/json**: <br> |
| 404 | Undocumented | **application/json**: <br> |
| default | Error | **application/json**: [ErrorResponse](#errorresponse)<br> |
### [GET] /unknown
#### Responses
| Code | Description | Schema |
| ---- | ----------- | ------ |
| 400 | Bad Request | **application/json**: <br> |
"""
patched = module._patch_union_response_markdown(markdown, spec_path)
assert (
"| 400 | Bad \\| Request | **application/json**: "
"[PluginError](#pluginerror)<br>[ErrorResponse](#errorresponse)<br> |"
) in patched
assert "| 200 | Success | **application/json**: object<br> |" in patched
assert "| 404 | Undocumented | **application/json**: <br> |" in patched
assert "| default | Error | **application/json**: [ErrorResponse](#errorresponse)<br> |" in patched
assert patched.endswith("| 400 | Bad Request | **application/json**: <br> |\n")
def test_patch_wildcard_media_type_markdown_preserves_literal_wildcard() -> None:
module = _load_generate_swagger_markdown_docs_module()
patched = module._patch_wildcard_media_type_markdown("| 200 | Raw file. | ***/***: binary<br> |\n")
assert patched == "| 200 | Raw file. | `*/*`: binary<br> |\n"
def test_drop_null_values_for_markdown_does_not_mutate_openapi_source() -> None:
module = _load_generate_swagger_markdown_docs_module()
payload = {
"schema": {
"default": None,
"enum": ["value", None],
"properties": {"nullable": {"default": None}}, # pyrefly: ignore[implicit-any-empty-container]
}
}
converted = module._drop_null_values_for_markdown(payload)
assert converted == {
"schema": {
"enum": ["value", None],
"properties": {"nullable": {}},
}
}
assert payload["schema"]["default"] is None
assert payload["schema"]["properties"]["nullable"]["default"] is None
def test_patch_union_schema_markdown_ignores_unrenderable_shapes(tmp_path: Path) -> None:
module = _load_generate_swagger_markdown_docs_module()
spec_path = tmp_path / "console-openapi.json"
spec_path.write_text(
json.dumps(
{
"components": {
"schemas": {
"NotAMapping": [],
"BrokenUnion": {
"oneOf": [
{},
{"$ref": "#/components/schemas/Missing"},
{"$ref": "#/components/schemas/NoPropertyMapping"},
],
},
"NoPropertyMapping": {"properties": []},
},
}
}
),
encoding="utf-8",
)
assert module._schema_ref_name(None) is None
assert module._schema_markdown_type(None) == ""
assert module._schema_markdown_type({"anyOf": [{"type": "null"}]}) == ""
assert module._strip_trailing_line_whitespace("line \ncell\t \n") == "line\ncell\n"
assert module._replace_schema_table_type("unchanged", "Definition", "field", "") == "unchanged"
assert (
module._replace_schema_table_type(
"#### Definition\n#### Next\n| field | | | No |",
"Definition",
"field",
"string",
)
== "#### Definition\n#### Next\n| field | | | No |"
)
assert (
module._replace_schema_table_type("#### Definition\n| field |", "Definition", "field", "string")
== "#### Definition\n| field |"
)
assert module._patch_union_schema_markdown("#### BrokenUnion\n", spec_path) == "#### BrokenUnion\n"
def test_convert_spec_to_markdown_logs_converter_failure_without_overwriting_docs(
tmp_path: Path, monkeypatch: pytest.MonkeyPatch, caplog: pytest.LogCaptureFixture
) -> None:
module = _load_generate_swagger_markdown_docs_module()
spec_path = tmp_path / "console-openapi.json"
output_path = tmp_path / "console-openapi.md"
spec_path.write_text("{}", encoding="utf-8")
output_path.write_text("Existing documentation\n", encoding="utf-8")
def run_converter(args: list[str], **_kwargs: object) -> subprocess.CompletedProcess[str]:
return module.subprocess.CompletedProcess(
args=args, returncode=1, stdout="Loading converter", stderr="Unable to resolve npm runtime"
)
monkeypatch.setattr(module.subprocess, "run", run_converter)
with pytest.raises(module.subprocess.CalledProcessError) as exc_info:
module._convert_spec_to_markdown(spec_path, output_path)
assert exc_info.value.returncode == 1
assert exc_info.value.stdout == "Loading converter"
assert exc_info.value.stderr == "Unable to resolve npm runtime"
assert str(spec_path) in caplog.text
assert "Loading converter" in caplog.text
assert "Unable to resolve npm runtime" in caplog.text
assert output_path.read_text(encoding="utf-8") == "Existing documentation\n"
@pytest.mark.parametrize("required", ["Yes", "No"])
@pytest.mark.parametrize("content_count", [1, 2, 3])
def test_convert_spec_to_markdown_patches_generated_union_tables(
tmp_path: Path, monkeypatch: pytest.MonkeyPatch, required: str, content_count: int
) -> None:
module = _load_generate_swagger_markdown_docs_module()
spec_path = tmp_path / "console-openapi.json"
output_path = tmp_path / "console-openapi.md"
spec_path.write_text(
json.dumps(
{
"components": {
"schemas": {
"FormInputConfig": {
"oneOf": [
{"$ref": "#/components/schemas/ParagraphInputConfig"},
],
},
"ParagraphInputConfig": {
"properties": {
"default": {
"anyOf": [
{"$ref": "#/components/schemas/StringSource"},
{"type": "null"},
],
"default": None,
},
},
},
},
}
}
),
encoding="utf-8",
)
media_types = ["application/json", "multipart/form-data", "application/x-www-form-urlencoded"][:content_count]
body_schema = "".join(f"**{media_type}**: string, enum: a\\|b<br>" for media_type in media_types)
def run_converter(args: list[str], **kwargs: object) -> subprocess.CompletedProcess[str]:
assert kwargs["check"] is False
converter_spec_path = Path(args[args.index("-i") + 1])
assert converter_spec_path != spec_path
converter_spec = json.loads(converter_spec_path.read_text(encoding="utf-8"))
converter_default_property = converter_spec["components"]["schemas"]["ParagraphInputConfig"]["properties"][
"default"
]
assert "default" not in converter_default_property
source_spec = json.loads(spec_path.read_text(encoding="utf-8"))
assert source_spec["components"]["schemas"]["ParagraphInputConfig"]["properties"]["default"]["default"] is None
markdown_path = Path(args[args.index("-o") + 1])
markdown_path.write_text(
"Intro line"
+ " \n"
+ """
#### FormInputConfig
| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| FormInputConfig | | | |
#### ParagraphInputConfig
| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| default | | | No |
"""
+ "\n#### Request Body\n\n| Required | Schema |\n| -------- | ------ |\n"
+ f"| {required} | "
+ " | ".join([body_schema] * content_count)
+ " |\n",
encoding="utf-8",
)
return module.subprocess.CompletedProcess(args=args, returncode=0, stdout="", stderr="")
monkeypatch.setattr(module.subprocess, "run", run_converter)
module._convert_spec_to_markdown(spec_path, output_path)
converted = output_path.read_text(encoding="utf-8")
assert "Intro line \n" not in converted
assert "Intro line\n" in converted
assert "| FormInputConfig | [ParagraphInputConfig](#paragraphinputconfig) | | |" in converted
assert "| default | [StringSource](#stringsource) | | No |" in converted
body_row = converted.split("| -------- | ------ |\n", 1)[1].strip()
assert [cell.strip() for cell in body_row.strip("|").split(" | ")] == [required, body_schema]
def test_request_body_patch_preserves_distinct_cells_and_other_tables() -> None:
module = _load_generate_swagger_markdown_docs_module()
markdown = """| Required | Schema |
| -------- | ------ |
| Yes | first | second |
| Name | Schema | Description |
| ---- | ------ | ----------- |
| Yes | same | same |
"""
assert module._patch_request_body_markdown(markdown) == markdown