#!/usr/bin/env python3 """Generate the current Flask route inventory as an OpenAPI 3.1 contract.""" from __future__ import annotations import argparse import ast import json import re from collections import defaultdict from pathlib import Path ROOT = Path(__file__).resolve().parents[1] OUTPUT = ROOT / "docs" / "architecture" / "OPENAPI.yaml" PREFIXES = { "meta_data": "/api/meta", "data_interface": "/api/interface", "data_rules": "/api/rules", "graph": "/api/graph", "system": "/api/system", "data_source": "/api/datasource", "data_development": "/api/development/v1", "data_flow": "/api/dataflow", "business_domain": "/api/bd", "data_factory": "/api/datafactory", "data_service": "/api/dataservice", "knowledge_base": "/api/knowledge", } SHORTHAND_METHODS = {"get", "post", "put", "patch", "delete"} EDGE_SAFE_KEY_PATTERN = ( "^(?!.*(?:raw|rows?|sql|credential|secret|private|password|token|local_path))" "[a-z][a-z0-9_]{0,79}$" ) def _edge_safe_schema_lines() -> list[str]: lines = [ " EdgeSafeSummary:", " type: object", " x-max-policy-depth: 12", " maxProperties: 64", f" propertyNames: {{type: string, minLength: 1, maxLength: 80, pattern: '{EDGE_SAFE_KEY_PATTERN}'}}", " additionalProperties: {$ref: '#/components/schemas/EdgeSafeValue12'}", " description: 'Policy-approved bounded metadata/statistics/health/diagnostic fields only; raw rows, SQL, credentials, and local paths are forbidden.'", " EdgeSafeScalar:", " anyOf:", " - {type: string, maxLength: 4096}", " - {type: integer, minimum: -9007199254740991, maximum: 9007199254740991}", " - {type: number, minimum: -1000000000000, maximum: 1000000000000}", " - {type: boolean}", " - {type: 'null'}", " EdgeSafeValue0: {$ref: '#/components/schemas/EdgeSafeScalar'}", ] for depth in range(1, 13): previous = depth - 1 lines.extend( [ f" EdgeSafeValue{depth}:", " anyOf:", " - {$ref: '#/components/schemas/EdgeSafeScalar'}", f" - {{type: array, maxItems: 100, items: {{$ref: '#/components/schemas/EdgeSafeValue{previous}'}}}}", f" - {{type: object, maxProperties: 32, propertyNames: {{type: string, minLength: 1, maxLength: 80, pattern: '{EDGE_SAFE_KEY_PATTERN}'}}, additionalProperties: {{$ref: '#/components/schemas/EdgeSafeValue{previous}'}}}}", ] ) lines.append(" EdgeSafeValue: {$ref: '#/components/schemas/EdgeSafeValue12'}") return lines RESPONSE_FIELDS = { ("data_development", "summary"): [ "scope", "metrics", ], ("data_development", "details"): [ "metric", "state", "records", "page", "page_size", "total", ], ("knowledge_base", "ask"): [ "query_id", "mode", "answer", "answer_status", "degraded_components", "citations", "evidence", "freshness_status", ], } CONNECTOR_REQUEST_SCHEMAS = { "/api/datasource/connectors/config/validate": "ConnectorConfigValidationRequest", "/api/datasource/connectors/runs": "ConnectorRunRequest", "/api/datasource/connectors/machine/runs": "MachineConnectorRunRequest", "/api/datasource/connectors/source-bindings": "ConnectorSourceBindingRequest", "/api/datasource/connectors/principals": "ConnectorPrincipalRequest", "/api/datasource/connectors/{connector_id}/{version}/health": "ConnectorHealthRequest", "/api/datasource/connectors/principals/{principal_uid}/credentials": "ConnectorCredentialRequest", "/api/datasource/connectors/credentials/{credential_uid}/{action}": "ConnectorCredentialRequest", "/api/datasource/graph": "ConnectorGraphRequest", } CONNECTOR_RESPONSE_SCHEMAS = { ("/api/datasource/connectors/manifests", "get"): "ConnectorManifestEnvelope", ("/api/datasource/connectors/runs", "get"): "ConnectorRunListEnvelope", ("/api/datasource/connectors/runs", "post"): "ConnectorRunResultEnvelope", ("/api/datasource/connectors/machine/runs", "post"): "ConnectorRunResultEnvelope", ( "/api/datasource/connectors/runs/{idempotency_key}/cancel", "post", ): "ConnectorRunRecordEnvelope", ( "/api/datasource/connectors/runs/{idempotency_key}/resume", "post", ): "ConnectorRunResultEnvelope", ( "/api/datasource/connectors/config/validate", "post", ): "ConnectorValidationEnvelope", ( "/api/datasource/connectors/{connector_id}/{version}/health", "post", ): "ConnectorHealthEnvelope", ( "/api/datasource/connectors/{connector_id}/{version}/compatibility", "get", ): "ConnectorCompatibilityEnvelope", ("/api/datasource/connectors/principals", "post"): "ConnectorPrincipalEnvelope", ( "/api/datasource/connectors/source-bindings", "post", ): "ConnectorSourceBindingEnvelope", ( "/api/datasource/connectors/principals/{principal_uid}/credentials", "post", ): "ConnectorCredentialEnvelope", ( "/api/datasource/connectors/credentials/{credential_uid}/{action}", "post", ): "ConnectorCredentialEnvelope", ("/api/datasource/graph", "post"): "ConnectorGraphEnvelope", } NO_REQUEST_BODY_PATHS = { "/api/datasource/connectors/runs/{idempotency_key}/cancel", "/api/datasource/connectors/runs/{idempotency_key}/resume", "/api/datasource/connectors/machine/runs/{idempotency_key}/cancel", "/api/datasource/connectors/machine/runs/{idempotency_key}/resume", "/api/datasource/connectors/source-bindings/{binding_uid}/revoke", "/api/datasource/edge/tasks/{task_id}/cancel", "/api/datasource/edge/gateways/{gateway_id}/revoke", } OPTIONAL_REQUEST_BODY_PATHS = { "/api/datasource/connectors/principals/{principal_uid}/credentials", "/api/datasource/connectors/credentials/{credential_uid}/{action}", } EDGE_REQUEST_SCHEMAS = { "/api/datasource/edge/enrollments": "EdgeEnrollmentRequest", "/api/datasource/edge/register": "EdgeRegisterRequest", "/api/datasource/edge/gateways/{gateway_id}/heartbeat": "EdgeHeartbeatRequest", "/api/datasource/edge/gateways/{gateway_id}/rotate": "EdgeRotateRequest", "/api/datasource/edge/tasks": "EdgeTaskContract", "/api/datasource/edge/gateways/{gateway_id}/tasks/pull": "EdgeMachineBinding", "/api/datasource/edge/gateways/{gateway_id}/tasks/{task_id}/outcome": "EdgeTaskOutcomeRequest", "/api/datasource/edge/gateways/{gateway_id}/events": "EdgeEventRequest", "/api/datasource/edge/gateways/{gateway_id}/reconcile": "EdgeReconcileRequest", "/api/datasource/edge/gateways/{gateway_id}/releases": "EdgeReleaseOfferRequest", "/api/datasource/edge/gateways/{gateway_id}/releases/ack": "EdgeReleaseAckRequest", } EDGE_RESPONSE_SCHEMAS = { ("/api/datasource/edge/enrollments", "post"): "EdgeEnrollmentEnvelope", ("/api/datasource/edge/register", "post"): "EdgeRegistrationEnvelope", ("/api/datasource/edge/gateways", "get"): "EdgeGatewayListEnvelope", ( "/api/datasource/edge/gateways/{gateway_id}/tasks/pull", "post", ): "EdgeTaskPullEnvelope", ( "/api/datasource/edge/gateways/{gateway_id}/events", "post", ): "EdgeEventAckEnvelope", ( "/api/datasource/edge/gateways/{gateway_id}/reconcile", "post", ): "EdgeReconcileResponse", ( "/api/datasource/edge/gateways/{gateway_id}/releases", "post", ): "EdgeReleaseEnvelope", } PRODUCTION_OBSERVABILITY_REQUEST_SCHEMAS = { "/api/datafactory/observability/operations/deliveries": "ProductionDeliveryRequest", } PRODUCTION_OBSERVABILITY_RESPONSE_SCHEMAS = { ( "/api/datafactory/observability/operations/deliveries", "post", ): "ProductionDeliveryEnvelope", } TRUSTED_DELIVERY_PERMISSIONS = { "/api/system/trusted-delivery/policy-versions": "security-governance:operate", "/api/system/trusted-delivery/policy-versions/activate": "security-governance:operate", "/api/system/trusted-delivery/policy-versions/rollback": "security-governance:operate", "/api/system/trusted-delivery/decisions": "security-governance:operate", "/api/system/trusted-delivery/provisions": "security-governance:operate", "/api/system/trusted-delivery/legal-holds": "security-governance:manage", "/api/system/trusted-delivery/legal-holds/release": "security-governance:manage", "/api/system/trusted-delivery/reclaim/preview": "security-governance:manage", "/api/system/trusted-delivery/reclaim/execute": "security-governance:manage", "/api/system/trusted-delivery/subscriptions": "security-governance:operate", "/api/system/trusted-delivery/subscriptions/{subscription_uid}/activate": "security-governance:operate", "/api/system/trusted-delivery/subscriptions/{subscription_uid}/pause": "security-governance:operate", "/api/system/trusted-delivery/subscriptions/{subscription_uid}/resume": "security-governance:operate", "/api/system/trusted-delivery/subscriptions/{subscription_uid}/terminate": "security-governance:operate", "/api/system/trusted-delivery/subscriptions/deliveries/{delivery_uid}/compensate": "security-governance:manage", "/api/system/trusted-delivery/subscriptions/anomalies": "security-governance:operate", "/api/system/trusted-delivery/controls/profiles/{profile_id}/active": "security-governance:read", "/api/system/trusted-delivery/controls/release-gates/evaluate": "security-governance:operate", "/api/system/trusted-delivery/controls/profiles/activate": "security-governance:manage", "/api/system/trusted-delivery/controls/profiles/rollback": "security-governance:manage", "/api/system/trusted-delivery/controls/capability-approvals": "security-governance:manage", "/api/system/trusted-delivery/controls/evidence": "security-governance:read", "/api/system/trusted-delivery/controls/destruction-approvals": "security-governance:manage", } TENANT_CONTROL_PERMISSIONS = { "/api/system/tenant/quota-claims": "identity:operate", "/api/system/tenant/approvals": "identity:manage", "/api/system/tenant/provisions": "identity:manage", "/api/system/tenant/lifecycle/activate": "identity:manage", "/api/system/tenant/lifecycle/freeze": "identity:manage", "/api/system/tenant/lifecycle/recover": "identity:manage", "/api/system/tenant/lifecycle/deletion-candidate": "identity:manage", "/api/system/tenant/lifecycle/rollback": "identity:manage", "/api/system/tenant/lifecycle/delete": "identity:manage", "/api/system/tenant/status": "identity:read", "/api/system/tenant/audit": "identity:read", "/api/system/tenant/manifests": "identity:read", } TENANT_CONTROL_BODY_FIELDS = { "/api/system/tenant/quota-claims": ( ("quota_name", "string"), ("amount", "string"), ("idempotency_key", "string"), ), "/api/system/tenant/provisions": (("idempotency_key", "string"),), "/api/system/tenant/approvals": ( ("operation", "string"), ("expected_fence", "string"), ("idempotency_key", "string"), ("backup_digest", "string"), ("retention_seconds", "string"), ), "/api/system/tenant/lifecycle/activate": ( ("expected_fence", "string"), ("idempotency_key", "string"), ("approval_ref", "string"), ("backup_digest", "string"), ("retention_seconds", "string"), ), "/api/system/tenant/lifecycle/freeze": ( ("expected_fence", "string"), ("idempotency_key", "string"), ("approval_ref", "string"), ("backup_digest", "string"), ("retention_seconds", "string"), ), "/api/system/tenant/lifecycle/recover": ( ("expected_fence", "string"), ("idempotency_key", "string"), ("approval_ref", "string"), ("backup_digest", "string"), ("retention_seconds", "string"), ), "/api/system/tenant/lifecycle/deletion-candidate": ( ("expected_fence", "string"), ("idempotency_key", "string"), ("approval_ref", "string"), ("backup_digest", "string"), ("retention_seconds", "string"), ), "/api/system/tenant/lifecycle/rollback": ( ("expected_fence", "string"), ("idempotency_key", "string"), ("approval_ref", "string"), ("backup_digest", "string"), ("retention_seconds", "string"), ), "/api/system/tenant/lifecycle/delete": ( ("expected_fence", "string"), ("idempotency_key", "string"), ("approval_ref", "string"), ("backup_digest", "string"), ("retention_seconds", "string"), ), } TENANT_CONTROL_REQUIRED_FIELDS = { path: tuple(field for field, _ in fields) for path, fields in TENANT_CONTROL_BODY_FIELDS.items() if "/lifecycle/" not in path } TENANT_CONTROL_REQUIRED_FIELDS.update( { path: ("expected_fence", "idempotency_key") for path in TENANT_CONTROL_BODY_FIELDS if "/lifecycle/" in path } ) TENANT_CONTROL_REQUIRED_FIELDS["/api/system/tenant/approvals"] = ( "operation", "expected_fence", "idempotency_key", ) BI_AI_CATALOG_PERMISSIONS = { "/api/system/bi-ai-catalog/local-fixture/sync": "bi-ai-catalog:manage", "/api/system/bi-ai-catalog/assets/search": "bi-ai-catalog:read", "/api/system/bi-ai-catalog/assets/{external_uid}/impact": "bi-ai-catalog:read", "/api/system/bi-ai-catalog/audit": "bi-ai-catalog:read", } METERING_SHOWBACK_PERMISSIONS = { "/api/system/metering/events": "metering:manage", "/api/system/metering/allocations": "metering:manage", "/api/system/metering/budgets": "metering:manage", "/api/system/metering/allocation-replay": "metering:read", "/api/system/metering/showback": "metering:read", "/api/system/metering/reconciliation": "metering:read", } METERING_SHOWBACK_BODY_FIELDS = { "/api/system/metering/events": ( ("schema_version", "integer"), ("event_uid", "string"), ("event_kind", "string"), ("occurred_at", "string"), ("window_start", "string"), ("window_end", "string"), ("quantity", "string"), ("unit", "string"), ("idempotency_key", "string"), ("evidence", "object"), ("mapping", "object"), ), "/api/system/metering/allocations": ( ("schema_version", "integer"), ("rule_uid", "string"), ("rule_version", "integer"), ("effective_start", "string"), ("effective_end", "string"), ("mapping", "object"), ("allocations", "array"), ), "/api/system/metering/budgets": ( ("schema_version", "integer"), ("budget_uid", "string"), ("window", "string"), ("mapping", "object"), ("limit_micros", "integer"), ("threshold_micros", "integer"), ), } METERING_SHOWBACK_REQUIRED_FIELDS = { "/api/system/metering/events": tuple(field for field, _ in METERING_SHOWBACK_BODY_FIELDS["/api/system/metering/events"]), "/api/system/metering/allocations": tuple(field for field, _ in METERING_SHOWBACK_BODY_FIELDS["/api/system/metering/allocations"]), "/api/system/metering/budgets": tuple(field for field, _ in METERING_SHOWBACK_BODY_FIELDS["/api/system/metering/budgets"]), } METERING_SHOWBACK_QUERY_PARAMS = { "/api/system/metering/showback": (("window", "string"),), "/api/system/metering/reconciliation": (("window", "string"),), "/api/system/metering/allocation-replay": (("window", "string"), ("rule_uid", "string"), ("rule_version", "integer")), } BI_AI_CATALOG_BODY_FIELDS = { "/api/system/bi-ai-catalog/local-fixture/sync": (), "/api/system/bi-ai-catalog/assets/search": ( ("query", "string"), ("filters", "object"), ), } BI_AI_CATALOG_REQUIRED_FIELDS = { "/api/system/bi-ai-catalog/local-fixture/sync": (), "/api/system/bi-ai-catalog/assets/search": ("query", "filters"), } EDGE_MACHINE_PATHS = { "/api/datasource/edge/gateways/{gateway_id}/heartbeat", "/api/datasource/edge/gateways/{gateway_id}/tasks/pull", "/api/datasource/edge/gateways/{gateway_id}/tasks/{task_id}/outcome", "/api/datasource/edge/gateways/{gateway_id}/events", "/api/datasource/edge/gateways/{gateway_id}/reconcile", "/api/datasource/edge/gateways/{gateway_id}/releases/ack", } EDGE_CREATED_PATHS = { "/api/datasource/edge/enrollments", "/api/datasource/edge/register", "/api/datasource/edge/tasks", "/api/datasource/edge/gateways/{gateway_id}/releases", } def quoted(value: str) -> str: return json.dumps(value, ensure_ascii=False) def route_path(raw_path: str) -> tuple[str, list[dict[str, str]]]: parameters: list[dict[str, str]] = [] def replace(match: re.Match[str]) -> str: converter = match.group(1) or "string" name = match.group(2) schema_type = "integer" if converter in {"int", "float"} else "string" parameters.append({"name": name, "type": schema_type}) return "{" + name + "}" return re.sub( r"<(?:([a-zA-Z_]+):)?([a-zA-Z_][a-zA-Z0-9_]*)>", replace, raw_path ), parameters def extract_routes() -> list[dict[str, object]]: routes: list[dict[str, object]] = [] for module, prefix in PREFIXES.items(): for route_file in sorted((ROOT / "app" / "api" / module).glob("*.py")): if route_file.name == "__init__.py": continue tree = ast.parse(route_file.read_text(encoding="utf-8")) for node in tree.body: if not isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)): continue for decorator in node.decorator_list: if not isinstance(decorator, ast.Call): continue function = decorator.func if not ( isinstance(function, ast.Attribute) and isinstance(function.value, ast.Name) and function.value.id == "bp" and decorator.args ): continue if function.attr == "route": methods = ["GET"] for keyword in decorator.keywords: if keyword.arg == "methods": methods = ast.literal_eval(keyword.value) elif function.attr in SHORTHAND_METHODS: methods = [function.attr.upper()] else: continue raw_path = ast.literal_eval(decorator.args[0]) path, parameters = route_path(prefix + raw_path) summary = ( ast.get_docstring(node) or node.name.replace("_", " ") ).splitlines()[0] for method in methods: routes.append( { "path": path, "method": method.lower(), "tag": module, "operation_id": f"{module}_{node.name}_{method.lower()}", "summary": summary, "parameters": parameters, "source": str(route_file.relative_to(ROOT)), } ) return sorted(routes, key=lambda item: (str(item["path"]), str(item["method"]))) def render(routes: list[dict[str, object]]) -> str: by_path: dict[str, list[dict[str, object]]] = defaultdict(list) for route in routes: by_path[str(route["path"])].append(route) lines = [ "openapi: 3.1.0", "info:", ' title: "DataOps Platform API（当前代码基线）"', ' version: "2026-08-09"', ' description: "由 scripts/generate_openapi.py 从 app/api/*/routes.py 生成。请求体与响应细节仍以现有专项 API 文档和代码为准。"', f"x-route-count: {len(routes)}", "servers:", ' - url: "http://localhost:15500"', ' description: "全本地隔离测试后端"', "tags:", ] for tag in PREFIXES: lines.extend([f" - name: {tag}", f" description: {quoted(PREFIXES[tag])}"]) lines.append("paths:") for path, operations in sorted(by_path.items()): lines.append(f" {quoted(path)}:") for operation in operations: lines.extend( [ f" {operation['method']}:", f" tags: [{operation['tag']}]", f" operationId: {operation['operation_id']}", f" summary: {quoted(str(operation['summary']))}", f" x-source: {quoted(str(operation['source']))}", ] ) if path.startswith("/api/datasource/edge/"): lines.extend( [ " x-max-request-bytes: 262144", " x-max-json-depth: 32", " x-max-json-nodes: 5000", ] ) parameters = operation["parameters"] if path.startswith("/api/datasource/connectors/machine/runs"): parameters = [ *parameters, { "name": "X-Connector-Credential", "type": "string", "header": True, }, ] if path == "/api/datasource/edge/register": parameters = [ *parameters, {"name": "X-Edge-Enrollment", "type": "string", "header": True}, { "name": "X-DataOps-Edge-Client-Verify", "type": "string", "header": True, }, { "name": "X-DataOps-Edge-Client-Cert", "type": "string", "header": True, }, { "name": "X-Edge-Certificate-SHA256", "type": "string", "header": True, }, ] elif path in EDGE_MACHINE_PATHS: parameters = [ *parameters, {"name": "X-Edge-Credential", "type": "string", "header": True}, { "name": "X-DataOps-Edge-Client-Verify", "type": "string", "header": True, }, { "name": "X-DataOps-Edge-Client-Cert", "type": "string", "header": True, }, { "name": "X-Edge-Certificate-SHA256", "type": "string", "header": True, }, ] if path == "/api/datasource/edge/gateways" and operation["method"] == "get": parameters = [ *parameters, {"name": "limit", "type": "integer", "query": True}, {"name": "offset", "type": "integer", "query": True}, ] if path in METERING_SHOWBACK_QUERY_PARAMS: parameters = [ *parameters, *( {"name": name, "type": schema_type, "query": True, "required": True} for name, schema_type in METERING_SHOWBACK_QUERY_PARAMS[path] ), ] if parameters: lines.append(" parameters:") for parameter in parameters: lines.extend( [ f" - name: {parameter['name']}", f" in: {'header' if parameter.get('header') else 'query' if parameter.get('query') else 'path'}", f" required: {'true' if parameter.get('required') else 'false' if parameter.get('query') else 'true'}", " schema:", f" type: {parameter['type']}", ] ) if parameter["name"] in {"X-Edge-Credential", "X-Edge-Enrollment"}: lines.extend( [ " format: password", " writeOnly: true", ] ) if parameter["name"] == "limit": lines.extend( [" minimum: 1", " maximum: 100"] ) if parameter["name"] == "offset": lines.extend( [" minimum: 0", " maximum: 10000"] ) if ( path == "/api/datasource/connectors/credentials/{credential_uid}/{action}" and parameter["name"] == "action" ): lines.append(" enum: [revoke, rotate]") if ( operation["method"] in {"post", "put", "patch"} and path not in NO_REQUEST_BODY_PATHS ): connector_schema = CONNECTOR_REQUEST_SCHEMAS.get(path) request_schema = ( connector_schema or EDGE_REQUEST_SCHEMAS.get(path) or PRODUCTION_OBSERVABILITY_REQUEST_SCHEMAS.get(path) ) lines.extend( [ " requestBody:", " required: " + ( "false" if path in OPTIONAL_REQUEST_BODY_PATHS else "true" if request_schema or path in TENANT_CONTROL_BODY_FIELDS or path in BI_AI_CATALOG_BODY_FIELDS or path in METERING_SHOWBACK_BODY_FIELDS else "false" ), " content:", " application/json:", " schema:", f" $ref: '#/components/schemas/{request_schema}'" if request_schema else " type: object", ] ) if not request_schema: lines.append( " additionalProperties: false" if path in TRUSTED_DELIVERY_PERMISSIONS or path in TENANT_CONTROL_PERMISSIONS or path in BI_AI_CATALOG_PERMISSIONS or path in METERING_SHOWBACK_PERMISSIONS else " additionalProperties: true" ) if path in TENANT_CONTROL_BODY_FIELDS: fields = TENANT_CONTROL_BODY_FIELDS[path] lines.append( " required: [" + ", ".join(TENANT_CONTROL_REQUIRED_FIELDS[path]) + "]" ) lines.append(" properties:") for field, field_type in fields: lines.extend( [ f" {field}:", f" type: {field_type}", ] ) if ( path == "/api/system/tenant/quota-claims" and field == "amount" ): lines.append( " pattern: '^[0-9]+([.][0-9]{1,6})?$'" ) if path in BI_AI_CATALOG_BODY_FIELDS: fields = BI_AI_CATALOG_BODY_FIELDS[path] lines.append( " required: [" + ", ".join(BI_AI_CATALOG_REQUIRED_FIELDS[path]) + "]" ) if fields: lines.append(" properties:") for field, field_type in fields: lines.extend( [ f" {field}:", f" type: {field_type}", ] ) if path in METERING_SHOWBACK_BODY_FIELDS: fields = METERING_SHOWBACK_BODY_FIELDS[path] lines.append(" required: [" + ", ".join(METERING_SHOWBACK_REQUIRED_FIELDS[path]) + "]") lines.append(" properties:") for field, field_type in fields: lines.extend([f" {field}:", f" type: {field_type}"]) if field == "mapping": lines.extend([" additionalProperties: false", " required: [department, project, cost_center]", " properties:", " department: {type: string}", " project: {type: string}", " cost_center: {type: string}"]) elif field == "evidence": lines.extend([" additionalProperties: false", " required: [digest, reference]", " properties:", " digest: {type: string}", " reference: {type: string}"]) elif field == "allocations": lines.extend([" minItems: 1", " maxItems: 32", " items:", " type: object", " additionalProperties: false", " required: [target, weight_micros]", " properties:", " target: {type: string}", " weight_micros: {type: integer, minimum: 1, maximum: 1000000}"]) response_fields = RESPONSE_FIELDS.get( (str(operation["tag"]), str(operation["operation_id"]).split("_")[-2]) ) if response_fields: lines.append( " x-response-fields: [" + ", ".join(response_fields) + "]" ) connector_response = CONNECTOR_RESPONSE_SCHEMAS.get( (path, str(operation["method"])) ) edge_response = EDGE_RESPONSE_SCHEMAS.get((path, str(operation["method"]))) response_status = ( "201" if operation["method"] == "post" and ( path in EDGE_CREATED_PATHS or path in { "/api/system/bi-ai-catalog/local-fixture/sync", "/api/datasource/connectors/runs", "/api/datasource/connectors/machine/runs", "/api/datasource/connectors/principals", "/api/datasource/connectors/principals/{principal_uid}/credentials", "/api/datasource/connectors/source-bindings", "/api/datafactory/observability/operations/deliveries", "/api/system/tenant/quota-claims", "/api/system/tenant/provisions", "/api/system/tenant/approvals", "/api/system/metering/events", "/api/system/metering/allocations", "/api/system/metering/budgets", } ) else "200" ) if path.startswith("/api/datasource/connectors"): required_permission = ( "machine-credential" if path.startswith("/api/datasource/connectors/machine/runs") else ( "connectors:manage" if "/source-bindings" in path else ( "connectors:read" if operation["method"] == "get" else ( "connectors:manage" if "/principals" in path or "/credentials" in path else "connectors:operate" ) ) ) ) lines.append( f" x-required-permission: {quoted(required_permission)}" ) elif path == "/api/datasource/graph": lines.append(' x-required-permission: "connectors:read"') elif path == "/api/datafactory/observability/operations/deliveries": lines.append( ' x-required-permission: "data-observability:operate"' ) elif path in TRUSTED_DELIVERY_PERMISSIONS: lines.append( f" x-required-permission: {quoted(TRUSTED_DELIVERY_PERMISSIONS[path])}" ) elif path in TENANT_CONTROL_PERMISSIONS: lines.append( f" x-required-permission: {quoted(TENANT_CONTROL_PERMISSIONS[path])}" ) elif path in BI_AI_CATALOG_PERMISSIONS: lines.append( f" x-required-permission: {quoted(BI_AI_CATALOG_PERMISSIONS[path])}" ) elif path in METERING_SHOWBACK_PERMISSIONS: lines.append(f" x-required-permission: {quoted(METERING_SHOWBACK_PERMISSIONS[path])}") elif path.startswith("/api/datasource/edge"): if path == "/api/datasource/edge/register": permission = "one-time-enrollment+mTLS" elif path in EDGE_MACHINE_PATHS: permission = "edge-credential+mTLS" elif ( path == "/api/datasource/edge/gateways" and operation["method"] == "get" ): permission = "edge-gateways:read" elif path == "/api/datasource/edge/enrollments": permission = "edge-gateways:manage" else: permission = "edge-gateways:operate" lines.append(f" x-required-permission: {quoted(permission)}") if path == "/api/datasource/edge/register": lines.extend( [ " security:", " - mutualTLS: []", " edgeEnrollment: []", ] ) elif path in EDGE_MACHINE_PATHS: lines.extend( [ " security:", " - mutualTLS: []", " edgeCredential: []", ] ) else: lines.extend([" security:", " - bearerAuth: []"]) success_headers = ( [ " headers:", " Cache-Control:", " required: true", " schema: {type: string, const: no-store}", ] if path.startswith("/api/datasource/edge") or path == "/api/datafactory/observability/operations/deliveries" or path in TRUSTED_DELIVERY_PERMISSIONS or path in TENANT_CONTROL_PERMISSIONS or path in BI_AI_CATALOG_PERMISSIONS or path in METERING_SHOWBACK_PERMISSIONS else [] ) lines.extend( [ " responses:", f' "{response_status}":', ' description: "请求已由当前实现处理"', *success_headers, " content:", " application/json:", " schema:", f" $ref: '#/components/schemas/{connector_response or edge_response or PRODUCTION_OBSERVABILITY_RESPONSE_SCHEMAS.get((path, str(operation['method']))) or ('EdgeApiEnvelope' if path.startswith('/api/datasource/edge') else 'ApiEnvelope')}'", " default:", ' description: "错误响应"', *success_headers, " content:", " application/json:", " schema:", f" $ref: '#/components/schemas/{'ConnectorErrorEnvelope' if path.startswith('/api/datasource/connectors') or path == '/api/datasource/graph' else 'EdgeErrorEnvelope' if path.startswith('/api/datasource/edge') else 'ApiEnvelope'}'", ] ) lines.extend( [ "components:", " schemas:", " ApiEnvelope:", " type: object", " additionalProperties: true", " required: [code, message, data]", " properties:", " code:", " type: integer", " message:", " type: string", " data: {}", " error: {type: object}", " EdgeApiEnvelope:", " type: object", " additionalProperties: false", " required: [code, message, data]", " properties: {code: {type: integer}, message: {type: string}, data: {type: object}}", " ProductionDeliveryRequest:", " type: object", " additionalProperties: false", " required: [incident_uid, alert_uid, channel, summary]", " properties: {incident_uid: {type: string, format: uuid}, alert_uid: {type: string, format: uuid}, channel: {type: string, enum: [monitoring, smtp, enterprise_collaboration, on_call, itsm]}, summary: {type: string, minLength: 1, maxLength: 160}}", " ProductionDeliveryRecord:", " type: object", " additionalProperties: false", " required: [uid, incident_uid, alert_uid, channel, status, attempt_count, lease_fence]", " properties: {uid: {type: string, format: uuid}, incident_uid: {type: string, format: uuid}, alert_uid: {type: string, format: uuid}, channel: {type: string, enum: [monitoring, smtp, enterprise_collaboration, on_call, itsm]}, status: {type: string, enum: [pending, processing, delivered, dead_letter, compensated]}, attempt_count: {type: integer, minimum: 0, maximum: 3}, lease_fence: {type: integer, minimum: 0}, next_attempt_at: {type: string, format: date-time}, lease_owner: {type: [string, 'null'], maxLength: 80}, lease_expires_at: {type: [string, 'null'], format: date-time}, last_reason_code: {type: [string, 'null'], maxLength: 64}, compensation_reason_code: {type: [string, 'null'], maxLength: 64}, compensation_receipt_code: {type: [string, 'null'], maxLength: 64}, idempotency_key: {type: string, maxLength: 200}, payload_digest: {type: string, pattern: '^[a-f0-9]{64}$'}, created_at: {type: string, format: date-time}, updated_at: {type: string, format: date-time}}", " ProductionDeliveryEnvelope:", " type: object", " additionalProperties: false", " required: [code, message, data]", " properties: {code: {const: 200}, message: {type: string}, data: {$ref: '#/components/schemas/ProductionDeliveryRecord'}}", " EdgeErrorEnvelope:", " type: object", " additionalProperties: false", " required: [code, message, data, error]", " properties: {code: {type: integer}, message: {type: string}, data: {type: 'null'}, error: {type: object, additionalProperties: false, required: [code], properties: {code: {type: string, maxLength: 80}}}}", " EdgeMachineBinding:", " type: object", " additionalProperties: false", " required: [environment, network_zone, generation]", " properties: {environment: {type: string, enum: [development, staging, production]}, network_zone: {type: string, minLength: 1, maxLength: 120}, generation: {type: integer, minimum: 1}}", " EdgeEnrollmentRequest:", " type: object", " additionalProperties: false", " required: [gateway_name, environment, network_zone, policy_digest, allowed_control_hosts, allowed_proxy_hosts, expected_certificate_sha256]", " properties: {gateway_name: {type: string, minLength: 1, maxLength: 200}, environment: {type: string, enum: [development, staging, production]}, network_zone: {type: string, minLength: 1, maxLength: 120}, policy_digest: {$ref: '#/components/schemas/Sha256Digest'}, allowed_control_hosts: {$ref: '#/components/schemas/EdgeExactHosts'}, allowed_proxy_hosts: {$ref: '#/components/schemas/EdgeExactHosts'}, expected_certificate_sha256: {$ref: '#/components/schemas/Sha256Digest'}, ttl_seconds: {type: integer, minimum: 60, maximum: 86400}}", " EdgeRegisterRequest:", " type: object", " additionalProperties: false", " required: [gateway_id, environment, network_zone, policy_digest, allowed_control_hosts, allowed_proxy_hosts, version]", " properties: {gateway_id: {type: string, format: uuid}, environment: {type: string, enum: [development, staging, production]}, network_zone: {type: string, minLength: 1, maxLength: 120}, policy_digest: {$ref: '#/components/schemas/Sha256Digest'}, allowed_control_hosts: {$ref: '#/components/schemas/EdgeExactHosts'}, allowed_proxy_hosts: {$ref: '#/components/schemas/EdgeExactHosts'}, version: {$ref: '#/components/schemas/EdgeAgentVersion'}}", " EdgeHeartbeatRequest:", " type: object", " additionalProperties: false", " required: [environment, network_zone, generation, version, safe_summary]", " properties: {environment: {type: string, enum: [development, staging, production]}, network_zone: {type: string, minLength: 1, maxLength: 120}, generation: {type: integer, minimum: 1}, version: {$ref: '#/components/schemas/EdgeAgentVersion'}, safe_summary: {$ref: '#/components/schemas/EdgeSafeSummary'}}", " EdgeRotateRequest:", " type: object", " additionalProperties: false", " required: [certificate_sha256, request_id]", " properties: {certificate_sha256: {$ref: '#/components/schemas/Sha256Digest'}, request_id: {type: string, minLength: 1, maxLength: 255}}", " Sha256Digest: {type: string, pattern: '^[a-f0-9]{64}$'}", " Ed25519Signature: {type: string, pattern: '^[a-f0-9]{128}$'}", " EdgeExactHosts: {type: array, maxItems: 32, uniqueItems: true, items: {type: string, pattern: '^[a-z0-9][a-z0-9.-]*[a-z0-9]$'}}", *_edge_safe_schema_lines(), " EdgeIdentifier: {type: string, minLength: 1, maxLength: 255, pattern: '^[A-Za-z0-9][A-Za-z0-9._:-]{0,254}$'}", " EdgeCursor: {type: [string, 'null'], minLength: 1, maxLength: 255, pattern: '^[A-Za-z0-9][A-Za-z0-9._:-]{0,254}$'}", " EdgeAgentVersion: {type: string, minLength: 1, maxLength: 80, pattern: '^[A-Za-z0-9][A-Za-z0-9._+-]{0,79}$'}", " EdgeVersion: {type: string, pattern: '^(0|[1-9][0-9]{0,9})\\.(0|[1-9][0-9]{0,9})\\.(0|[1-9][0-9]{0,9})$'}", " EdgeTaskContract:", " type: object", " additionalProperties: false", " required: [task_id, gateway_id, environment, network_zone, purpose, classification, task_type, contract_version, deadline_at, attempt, idempotency_key, policy_digest]", " properties: {task_id: {$ref: '#/components/schemas/EdgeIdentifier'}, gateway_id: {type: string, format: uuid}, environment: {type: string, enum: [development, staging, production]}, network_zone: {type: string, minLength: 1, maxLength: 120}, purpose: {type: string, minLength: 1, maxLength: 255}, classification: {type: string, enum: [raw, recent_detail, restricted, desensitized_metadata, statistics, lineage, evidence]}, task_type: {type: string, enum: [collect, profile, quality, lineage, controlled_query]}, contract_version: {const: 1}, deadline_at: {type: string, format: date-time}, attempt: {type: integer, minimum: 1, maximum: 5}, idempotency_key: {$ref: '#/components/schemas/EdgeIdentifier'}, policy_digest: {$ref: '#/components/schemas/Sha256Digest'}}", " EdgeSignedTaskEnvelope:", " type: object", " additionalProperties: false", " required: [task, authority_key_id, signature_algorithm, contract_digest, gateway_id, environment, network_zone, policy_digest, purpose, issued_at, expires_at, signature]", " properties: {task: {$ref: '#/components/schemas/EdgeTaskContract'}, authority_key_id: {type: string}, signature_algorithm: {const: Ed25519}, contract_digest: {$ref: '#/components/schemas/Sha256Digest'}, gateway_id: {type: string}, environment: {type: string}, network_zone: {type: string}, policy_digest: {$ref: '#/components/schemas/Sha256Digest'}, purpose: {type: string}, issued_at: {type: string, format: date-time}, expires_at: {type: string, format: date-time}, signature: {$ref: '#/components/schemas/Ed25519Signature'}}", " EdgeEventContract:", " type: object", " additionalProperties: false", " required: [event_id, task_id, gateway_id, environment, network_zone, purpose, classification, contract_version, occurred_at, attempt, idempotency_key, policy_digest, payload]", " properties: {event_id: {type: string}, task_id: {type: string}, gateway_id: {type: string}, environment: {type: string}, network_zone: {type: string}, purpose: {type: string}, classification: {type: string, enum: [desensitized_metadata, statistics, lineage, evidence, health_summary, diagnostic_summary]}, contract_version: {const: 1}, occurred_at: {type: string, format: date-time}, attempt: {type: integer, minimum: 1, maximum: 5}, idempotency_key: {type: string}, policy_digest: {$ref: '#/components/schemas/Sha256Digest'}, payload: {$ref: '#/components/schemas/EdgeSafeSummary'}}", " EdgeEventRequest:", " type: object", " additionalProperties: false", " required: [environment, network_zone, generation, event, lease_token]", " properties: {environment: {type: string}, network_zone: {type: string}, generation: {type: integer, minimum: 1}, event: {$ref: '#/components/schemas/EdgeEventContract'}, lease_token: {type: string, writeOnly: true}}", " EdgeTaskOutcomeRequest:", " type: object", " additionalProperties: false", " required: [environment, network_zone, generation, outcome, lease_token, safe_summary]", " properties: {environment: {type: string}, network_zone: {type: string}, generation: {type: integer, minimum: 1}, outcome: {type: string, enum: [completed, failed, cancelled]}, lease_token: {type: string, writeOnly: true}, safe_summary: {$ref: '#/components/schemas/EdgeSafeSummary'}}", " EdgeReconcileRequest:", " type: object", " additionalProperties: false", " required: [environment, network_zone, generation]", " properties: {environment: {type: string, enum: [development, staging, production]}, network_zone: {type: string, minLength: 1, maxLength: 120}, generation: {type: integer, minimum: 1}, limit: {type: integer, minimum: 1, maximum: 100}, cancel_cursor: {$ref: '#/components/schemas/EdgeCursor'}, release_cursor: {$ref: '#/components/schemas/EdgeCursor'}}", " EdgeReconcileResponse:", " type: object", " additionalProperties: false", " required: [code, message, data]", " properties: {code: {type: integer}, message: {type: string, maxLength: 200}, data: {type: object, additionalProperties: false, required: [cancelled_task_ids, cancel_next_cursor, release_offers, release_next_cursor, release_baseline], properties: {cancelled_task_ids: {type: array, maxItems: 50, items: {$ref: '#/components/schemas/EdgeIdentifier'}}, cancel_next_cursor: {$ref: '#/components/schemas/EdgeCursor'}, release_offers: {type: array, maxItems: 50, items: {$ref: '#/components/schemas/EdgeReleaseManifest'}}, release_next_cursor: {$ref: '#/components/schemas/EdgeCursor'}, release_baseline: {oneOf: [{$ref: '#/components/schemas/EdgeReleaseManifest'}, {type: 'null'}]}}}}", " EdgeReleaseOfferRequest:", " type: object", " additionalProperties: false", " required: [version, artifact_digest, artifact_name, deadline_at, rollback_version, request_id]", " properties: {version: {$ref: '#/components/schemas/EdgeVersion'}, artifact_digest: {$ref: '#/components/schemas/Sha256Digest'}, artifact_name: {type: string, minLength: 1, maxLength: 255, pattern: '^[^/\\\\]+$'}, deadline_at: {type: string, format: date-time}, rollback_version: {$ref: '#/components/schemas/EdgeVersion'}, request_id: {$ref: '#/components/schemas/EdgeIdentifier'}}", " EdgeReleaseAckRequest:", " type: object", " additionalProperties: false", " required: [environment, network_zone, generation, release_id, outcome, safe_summary]", " properties: {environment: {type: string}, network_zone: {type: string}, generation: {type: integer, minimum: 1}, release_id: {type: string, format: uuid}, outcome: {type: string, enum: [accepted, installed, failed, rollback]}, safe_summary: {$ref: '#/components/schemas/EdgeSafeSummary'}}", " EdgeReleaseManifest:", " type: object", " additionalProperties: false", " required: [release_id, version, rollback_version, artifact_digest, artifact_name, deadline_at, status, signature_algorithm, key_id, manifest_digest, signature]", " properties: {release_id: {$ref: '#/components/schemas/EdgeIdentifier'}, version: {$ref: '#/components/schemas/EdgeVersion'}, rollback_version: {$ref: '#/components/schemas/EdgeVersion'}, artifact_digest: {$ref: '#/components/schemas/Sha256Digest'}, artifact_name: {type: string, minLength: 1, maxLength: 255, pattern: '^[^/\\\\]+$'}, deadline_at: {type: string, format: date-time}, status: {type: string, enum: [offered, accepted, failed, installed, rolled_back]}, signature_algorithm: {const: Ed25519}, key_id: {$ref: '#/components/schemas/EdgeIdentifier'}, manifest_digest: {$ref: '#/components/schemas/Sha256Digest'}, signature: {$ref: '#/components/schemas/Ed25519Signature'}}", " EdgeEnrollmentEnvelope:", " type: object", " additionalProperties: false", " required: [code, message, data]", " properties: {code: {type: integer}, message: {type: string}, data: {type: object, additionalProperties: false, required: [enrollment_id, gateway_id, enrollment_token, expires_in, returned_once], properties: {enrollment_id: {type: string, format: uuid}, gateway_id: {type: string, format: uuid}, enrollment_token: {type: string, writeOnly: true}, expires_in: {type: integer}, returned_once: {const: true}}}}", " EdgeRegistrationEnvelope:", " type: object", " additionalProperties: false", " required: [code, message, data]", " properties: {code: {type: integer}, message: {type: string}, data: {type: object, additionalProperties: false, required: [gateway_id, generation, certificate_sha256, credential, credential_returned_once], properties: {gateway_id: {type: string, format: uuid}, generation: {type: integer}, certificate_sha256: {$ref: '#/components/schemas/Sha256Digest'}, credential: {type: string, writeOnly: true}, credential_returned_once: {const: true}}}}", " EdgeGatewayListEnvelope:", " type: object", " additionalProperties: false", " required: [code, message, data]", " properties: {code: {type: integer}, message: {type: string}, data: {type: object, additionalProperties: false, required: [gateways], properties: {gateways: {type: array, maxItems: 100, items: {type: object, description: 'Bounded gateway metadata; credential/token/private key are never included.'}}}}}", " EdgeTaskPullEnvelope:", " type: object", " additionalProperties: false", " required: [code, message, data]", " properties: {code: {type: integer}, message: {type: string}, data: {oneOf: [{type: object, additionalProperties: false, required: [task], properties: {task: {type: 'null'}}}, {type: object, additionalProperties: false, required: [task, signed_task_envelope, lease_token, lease_expires_at], properties: {task: {$ref: '#/components/schemas/EdgeTaskContract'}, signed_task_envelope: {$ref: '#/components/schemas/EdgeSignedTaskEnvelope'}, lease_token: {type: string, writeOnly: true}, lease_expires_at: {type: string, format: date-time}}}]}}", " EdgeEventAckEnvelope:", " type: object", " additionalProperties: false", " required: [code, message, data]", " properties: {code: {type: integer}, message: {type: string}, data: {type: object, additionalProperties: false, required: [event_id, event_digest, remote_lease_digest, received_at, status], properties: {event_id: {type: string}, event_digest: {$ref: '#/components/schemas/Sha256Digest'}, remote_lease_digest: {$ref: '#/components/schemas/Sha256Digest'}, received_at: {type: string, format: date-time}, status: {const: accepted}}}}", " EdgeReleaseEnvelope:", " type: object", " additionalProperties: false", " required: [code, message, data]", " properties: {code: {type: integer}, message: {type: string, maxLength: 200}, data: {type: object, additionalProperties: false, required: [release_id, status, version, artifact_digest, rollback_version, manifest], properties: {release_id: {type: string, format: uuid}, status: {type: string, enum: [offered, accepted, failed, installed, rolled_back]}, version: {$ref: '#/components/schemas/EdgeVersion'}, artifact_digest: {$ref: '#/components/schemas/Sha256Digest'}, rollback_version: {$ref: '#/components/schemas/EdgeVersion'}, manifest: {$ref: '#/components/schemas/EdgeReleaseManifest'}}}}", " ConnectorConfigValidationRequest:", " type: object", " additionalProperties: false", " required: [connector_id, version, config]", " properties:", " connector_id: {type: string, minLength: 3, maxLength: 64}", " version: {type: string, pattern: '^[0-9]+\\.[0-9]+\\.[0-9]+'}", " config: {type: object}", " ConnectorRunRequest:", " type: object", " additionalProperties: false", " required: [connector_id, version, source_uid, operation, config, scope, dry_run]", " properties:", " connector_id: {type: string}", " version: {type: string}", " source_uid: {type: string, format: uuid}", " operation: {type: string, enum: [discover, snapshot, incremental, lineage, profile, evidence]}", " config: {type: object}", " scope: {$ref: '#/components/schemas/ConnectorScope'}", " cursor: {type: object}", " checkpoint: {type: object}", " idempotency_key: {type: string, pattern: '^[a-f0-9]{64}$'}", " dry_run: {const: true}", " process_key: {type: string, minLength: 1, maxLength: 300}", " MachineConnectorRunRequest:", " type: object", " additionalProperties: false", " required: [connector_id, version, source_uid, business_domain_uid, environment, process_key, operation, scope]", " properties:", " connector_id: {type: string}", " version: {type: string}", " source_uid: {type: string, format: uuid}", " business_domain_uid: {type: string, format: uuid}", " environment: {type: string, enum: [development, staging, production]}", " process_key: {type: string, minLength: 1, maxLength: 300}", " operation: {type: string, enum: [discover, snapshot, incremental, lineage, profile, evidence]}", " scope: {$ref: '#/components/schemas/ConnectorScope'}", " cursor: {type: object}", " checkpoint: {type: object}", " idempotency_key: {type: string, pattern: '^[a-f0-9]{64}$'}", " dry_run: {type: boolean, default: false}", " ConnectorPrincipalRequest:", " type: object", " additionalProperties: false", " required: [connector_id, version, source_uid, business_domain_uid, environment, operations, scopes]", " properties:", " connector_id: {type: string}", " version: {type: string}", " source_uid: {type: string, format: uuid}", " business_domain_uid: {type: string, format: uuid}", " environment: {type: string, enum: [development, staging, production]}", " operations: {type: array, minItems: 1, uniqueItems: true, items: {type: string}}", " scopes: {$ref: '#/components/schemas/ConnectorScope'}", " source_binding_uid: {type: string, format: uuid}", " source_binding_version: {type: integer, minimum: 1}", " ConnectorSourceBindingRequest:", " type: object", " additionalProperties: false", " required: [connector_id, version, source_uid, business_domain_uid, environment, approved_config]", " properties:", " binding_uid: {type: string, format: uuid}", " connector_id: {type: string}", " version: {type: string}", " source_uid: {type: string, format: uuid}", " business_domain_uid: {type: string, format: uuid}", " environment: {type: string, enum: [development, staging, production]}", " approved_config: {type: object}", " ConnectorScope:", " type: object", " additionalProperties: false", " properties:", " include_schemas: {type: array, uniqueItems: true, items: {type: string, minLength: 1}}", " exclude_schemas: {type: array, uniqueItems: true, items: {type: string, minLength: 1}}", " include_tables: {type: array, uniqueItems: true, items: {type: string, minLength: 1}}", " exclude_tables: {type: array, uniqueItems: true, items: {type: string, minLength: 1}}", " ConnectorHealthRequest:", " type: object", " additionalProperties: false", " required: [config]", " properties: {config: {type: object}}", " ConnectorCredentialRequest:", " type: object", " additionalProperties: false", " properties: {ttl_seconds: {type: integer, minimum: 60, maximum: 900}}", " ConnectorGraphRequest:", " type: object", " additionalProperties: false", " properties: {source_uid: {type: string, format: uuid}, business_domain_uid: {type: string, format: uuid}, process_key: {type: string}, run_uid: {type: string, format: uuid}, limit: {type: integer, minimum: 1, maximum: 1000}}", " ConnectorManifestEnvelope:", " type: object", " additionalProperties: false", " required: [code, message, data]", " properties:", " code: {type: integer}", " message: {type: string}", " data: {type: object, additionalProperties: false, required: [manifests], properties: {manifests: {type: array, items: {$ref: '#/components/schemas/ConnectorManifest'}}}}", " ConnectorManifest:", " type: object", " additionalProperties: false", " required: [connector_id, version, sdk_version, display_name, capabilities, config_schema]", " properties: {connector_id: {type: string}, version: {type: string}, sdk_version: {type: string}, display_name: {type: string}, capabilities: {type: array, items: {type: string}}, config_schema: {type: object}}", " ConnectorOperationResult:", " type: object", " additionalProperties: false", " required: [records, cursor, checkpoint, evidence, status]", " properties: {records: {type: array, items: {type: object}}, cursor: {type: object}, checkpoint: {type: object}, evidence: {type: object}, status: {type: string, enum: [succeeded, dry_run]}}", " ConnectorRunResultEnvelope:", " type: object", " additionalProperties: false", " required: [code, message, data]", " properties: {code: {type: integer}, message: {type: string}, data: {$ref: '#/components/schemas/ConnectorOperationResult'}}", " ConnectorRunRecord:", " type: object", " additionalProperties: false", " required: [uid, idempotency_key, connector_id, connector_version, source_uid, operation, status, attempt_count, checkpoint_summary, cursor_summary, dry_run]", " properties: {uid: {type: string, format: uuid}, idempotency_key: {type: string}, connector_id: {type: string}, connector_version: {type: string}, source_uid: {type: string, format: uuid}, principal_uid: {type: [string, 'null'], format: uuid}, business_domain_uid: {type: [string, 'null'], format: uuid}, environment: {type: [string, 'null']}, process_key: {type: [string, 'null']}, operation: {type: string}, status: {type: string}, attempt_count: {type: integer}, checkpoint_summary: {type: object}, cursor_summary: {type: object}, scope: {type: object}, error_category: {type: [string, 'null']}, dry_run: {type: boolean}, created_at: {type: string}, updated_at: {type: string}}", " ConnectorRunRecordEnvelope:", " type: object", " additionalProperties: false", " required: [code, message, data]", " properties: {code: {type: integer}, message: {type: string}, data: {$ref: '#/components/schemas/ConnectorRunRecord'}}", " ConnectorRunListEnvelope:", " type: object", " additionalProperties: false", " required: [code, message, data]", " properties: {code: {type: integer}, message: {type: string}, data: {type: object, additionalProperties: false, required: [runs], properties: {runs: {type: array, items: {$ref: '#/components/schemas/ConnectorRunRecord'}}}}}", " ConnectorValidationEnvelope:", " type: object", " additionalProperties: false", " required: [code, message, data]", " properties: {code: {type: integer}, message: {type: string}, data: {type: object, required: [valid, config_keys], properties: {valid: {const: true}, config_keys: {type: array, items: {type: string}}}, additionalProperties: false}}", " ConnectorErrorEnvelope:", " type: object", " additionalProperties: false", " required: [code, message, data, error]", " properties:", " code: {type: integer}", " message: {type: string}", " data: {type: 'null'}", " error: {type: object, additionalProperties: false, required: [code, category, retryable], properties: {code: {const: CONNECTOR_ERROR}, category: {type: string, enum: [configuration, conflict, authentication, permission, rate_limit, timeout, upstream, contract, cancelled]}, retryable: {type: boolean}}}", " ConnectorHealthEnvelope:", " type: object", " additionalProperties: false", " required: [code, message, data]", " properties: {code: {type: integer}, message: {type: string}, data: {type: object, additionalProperties: false, required: [status, detail], properties: {status: {type: string}, detail: {type: string}}}}", " ConnectorCompatibilityEnvelope:", " type: object", " additionalProperties: false", " required: [code, message, data]", " properties: {code: {type: integer}, message: {type: string}, data: {type: object, additionalProperties: false, required: [compatible, connector_version, sdk_version, detail], properties: {compatible: {type: boolean}, connector_version: {type: string}, sdk_version: {type: string}, detail: {type: string}}}}", " ConnectorPrincipalEnvelope:", " type: object", " additionalProperties: false", " required: [code, message, data]", " properties: {code: {type: integer}, message: {type: string}, data: {type: object, additionalProperties: false, required: [principal_uid], properties: {principal_uid: {type: string, format: uuid}}}}", " ConnectorSourceBindingEnvelope:", " type: object", " additionalProperties: false", " required: [code, message, data]", " properties: {code: {type: integer}, message: {type: string}, data: {type: object, additionalProperties: false, required: [binding_uid, binding_version, status, rebound_principals], properties: {binding_uid: {type: string, format: uuid}, binding_version: {type: integer, minimum: 1}, status: {const: approved}, rebound_principals: {type: integer, minimum: 0}}}}", " ConnectorCredentialEnvelope:", " type: object", " additionalProperties: false", " required: [code, message, data]", " properties: {code: {type: integer}, message: {type: string}, data: {oneOf: [{type: object, additionalProperties: false, required: [credential_uid, credential, expires_in, returned_once], properties: {credential_uid: {type: string, format: uuid}, credential: {type: string, writeOnly: true}, expires_in: {type: integer}, returned_once: {const: true}}}, {type: object, additionalProperties: false, required: [revoked], properties: {revoked: {type: boolean}}}]}}", " ConnectorGraphEnvelope:", " type: object", " additionalProperties: false", " required: [code, message, data]", " properties: {code: {type: integer}, message: {type: string}, data: {type: object, additionalProperties: false, required: [nodes, edges, summary], properties: {nodes: {type: array, items: {type: object, additionalProperties: false, required: [type, key], properties: {type: {type: string, enum: [source, asset, process, business_domain, run]}, key: {type: string}}}}, edges: {type: array, items: {type: object}}, summary: {type: object, additionalProperties: false, required: [node_count, edge_count], properties: {node_count: {type: integer}, edge_count: {type: integer}}}}}}", " securitySchemes:", " mutualTLS:", " type: mutualTLS", " edgeCredential:", " type: apiKey", " in: header", " name: X-Edge-Credential", ' description: "One-time-returned edge credential; always combined with mutualTLS certificate proof."', " edgeEnrollment:", " type: apiKey", " in: header", " name: X-Edge-Enrollment", ' description: "Single-use enrollment token; always combined with mutualTLS certificate proof."', " bearerAuth:", " type: http", " scheme: bearer", " bearerFormat: JWT", ' description: "下一阶段统一认证方案；当前路由尚未全部接入。"', ] ) return "\n".join(lines) + "\n" def main(output: Path = OUTPUT) -> None: routes = extract_routes() if not routes: raise SystemExit("No Flask routes found") output.parent.mkdir(parents=True, exist_ok=True) output.write_text(render(routes), encoding="utf-8") try: label = output.relative_to(ROOT) except ValueError: label = output print(f"Generated {label} with {len(routes)} operations") if __name__ == "__main__": parser = argparse.ArgumentParser(description=__doc__) parser.add_argument("--output", type=Path, default=OUTPUT) args = parser.parse_args() main(args.output)