Skip to content

armgit / dify

Public Imported from GitHub
0

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.

23.0 KB
Raw Blame
"""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