convert_openapi_json_to_txt.py

import json

OPENAPI_FILE = "openapi.json"
OUTPUT_FILE = "openapi.txt"


def load_openapi():
    with open(OPENAPI_FILE, "r", encoding="utf-8") as f:
        return json.load(f)


def resolve_ref(ref, schemas):
    """
    Resolve:
    #/components/schemas/User
    """
    if not ref.startswith("#/components/schemas/"):
        return {"$ref": ref}

    name = ref.split("/")[-1]
    return schemas.get(name, {"$ref": ref})


def schema_to_text(schema, schemas, indent=0):
    pad = "  " * indent

    # References
    if "$ref" in schema:
        ref_name = schema["$ref"].split("/")[-1]
        return ref_name

    # Nullable / unions (FastAPI + Pydantic v2 commonly uses anyOf)
    if "anyOf" in schema:
        return " | ".join(schema_to_text(s, schemas, indent) for s in schema["anyOf"])

    if "oneOf" in schema:
        return " | ".join(schema_to_text(s, schemas, indent) for s in schema["oneOf"])

    if "allOf" in schema:
        return " & ".join(schema_to_text(s, schemas, indent) for s in schema["allOf"])

    schema_type = schema.get("type")

    # Objects
    if schema_type == "object" or "properties" in schema:
        lines = ["{"]
        required = set(schema.get("required", []))

        for name, prop in schema.get("properties", {}).items():
            marker = " (required)" if name in required else ""
            value = schema_to_text(prop, schemas, indent + 1)
            lines.append(f"{pad}  {name}{marker}: {value}")

        lines.append(f"{pad}}}")
        return "\n".join(lines)

    # Arrays
    if schema_type == "array":
        item_text = schema_to_text(
            schema.get("items", {}),
            schemas,
            indent + 1,
        )
        return f"list[{item_text}]"

    # Primitive types
    if schema_type == "string":
        fmt = schema.get("format")

        if fmt == "uuid":
            return "UUID"

        if fmt == "date-time":
            return "datetime"

        if fmt == "date":
            return "date"

        return "string"

    if schema_type == "integer":
        return "integer"

    if schema_type == "number":
        return "number"

    if schema_type == "boolean":
        return "boolean"

    if schema_type == "null":
        return "None"

    return "unknown"


def extract_request_schema(spec, schemas):
    request_body = spec.get("requestBody")
    if not request_body:
        return None

    content = request_body.get("content", {})

    for _, media in content.items():
        schema = media.get("schema")
        if schema:
            return schema_to_text(schema, schemas)

    return None


def extract_response_schema(response, schemas):
    content = response.get("content", {})

    for _, media in content.items():
        schema = media.get("schema")
        if schema:
            return schema_to_text(schema, schemas)

    return None


def generate_text(openapi):
    schemas = openapi.get("components", {}).get("schemas", {})
    output = []

    for path, methods in openapi.get("paths", {}).items():
        for method, spec in methods.items():
            output.append("=" * 80)
            output.append(f"{method.upper()} {path}")
            output.append("")

            if spec.get("summary"):
                output.append("Summary:")
                output.append(spec["summary"])
                output.append("")

            if spec.get("description"):
                output.append("Description:")
                output.append(spec["description"])
                output.append("")

            params = spec.get("parameters", [])
            if params:
                output.append("Parameters:")

                for p in params:
                    typ = p.get("schema", {}).get("type", "unknown")
                    req = "required" if p.get("required") else "optional"

                    output.append(f"- {p['name']} ({p['in']}): {typ} [{req}]")

                output.append("")

            request_schema = extract_request_schema(spec, schemas)

            if request_schema:
                output.append("Request Body:")
                output.append(request_schema)
                output.append("")

            output.append("Responses:")

            for status_code, response in spec.get("responses", {}).items():
                output.append("")
                output.append(f"{status_code} - {response.get('description', '')}")

                response_schema = extract_response_schema(
                    response,
                    schemas,
                )

                if response_schema:
                    output.append(response_schema)

            output.append("")
            output.append("")

    output.append("=" * 80)
    output.append("SCHEMAS")
    output.append("")

    for name, schema in sorted(schemas.items()):
        output.append(name)
        output.append(schema_to_text(schema, schemas))
        output.append("")
        output.append("")

    return "\n".join(output)


def main():
    openapi = load_openapi()

    text = generate_text(openapi)

    with open(OUTPUT_FILE, "w", encoding="utf-8") as f:
        f.write(text)

    print(f"Wrote {OUTPUT_FILE}")


if __name__ == "__main__":
    main()