Ministack: Free, open-source local AWS emulator - 60+ services, Terraform compatible, real databases. Free forever. MIT licensed.
Python awsaws-emulatoraws-localaws-sdkdevtoolsdockerdynamodbec2emulatorlambdalocalstacklocalstack-alternativeministackmock-awsopen-sourcepythons3sqsterraform
feat(apigateway): support REST API exports (#1175)
robert-pitt-foodhub848b202a33c9
diff --git a/ministack/services/apigateway_v1.py b/ministack/services/apigateway_v1.pyindex 692ab482..17a98125 100644--- a/ministack/services/apigateway_v1.py+++ b/ministack/services/apigateway_v1.py@@ -32,6 +32,7 @@ Control plane endpoints implemented:POST /restapis/{id}/stages — CreateStageGET /restapis/{id}/stages — GetStagesGET /restapis/{id}/stages/{stageName} — GetStage+ GET /restapis/{id}/stages/{stageName}/exports/{exportType} — GetExportPATCH /restapis/{id}/stages/{stageName} — UpdateStageDELETE /restapis/{id}/stages/{stageName} — DeleteStagePOST /restapis/{id}/authorizers — CreateAuthorizer@@ -88,6 +89,8 @@ import urllib.errorimport urllib.parseimport urllib.request+import yaml+from ministack.core.arn import ArnParseError, parse_arnfrom ministack.core.responses import AccountScopedDict, get_account_id, get_region, new_uuidfrom ministack.services.apigateway import _timeout_from_env, _urlopen_async@@ -1003,12 +1006,17 @@ async def handle_request(method, path, headers, body, query_params):# /restapis/{id}/stages[/{stageName}]elif sub == "stages":stage_name = parts[3] if len(parts) > 3 else None+ stage_sub = parts[4] if len(parts) > 4 else None+ export_type = parts[5] if len(parts) > 5 else Noneif not stage_name:if method == "POST":return _create_stage(api_id, data)if method == "GET":return _get_stages(api_id)- else:+ elif stage_sub == "exports":+ if method == "GET" and export_type and len(parts) == 6:+ return _get_export(api_id, stage_name, export_type, headers, query_params)+ elif stage_sub is None:if method == "GET":return _get_stage(api_id, stage_name)if method == "PATCH":@@ -1548,6 +1556,285 @@ def _import_operation(api_id, resource_id, http_method, operation):})+def _schema_ref(model_name, export_type):+ escaped_name = str(model_name).replace("~", "~0").replace("/", "~1")+ container = "components/schemas" if export_type == "oas30" else "definitions"+ return {"$ref": f"#/{container}/{escaped_name}"}+++def _export_model_schemas(api_id):+ schemas = {}+ for model_name, model in _models.get(api_id, {}).items():+ schema = model.get("schema")+ if isinstance(schema, dict):+ schemas[model_name] = schema+ continue+ try:+ schemas[model_name] = json.loads(schema or "{}")+ except (TypeError, json.JSONDecodeError):+ schemas[model_name] = {}+ return schemas+++def _export_method_parameters(method_obj, export_type):+ parameters = []+ location_map = {"path": "path", "querystring": "query", "header": "header"}+ for parameter_name, required in method_obj.get("requestParameters", {}).items():+ parts = parameter_name.split(".", 3)+ if len(parts) != 4 or parts[:2] != ["method", "request"]:+ continue+ location = location_map.get(parts[2])+ if location is None:+ continue+ parameter = {+ "name": parts[3],+ "in": location,+ "required": True if location == "path" else bool(required),+ }+ if export_type == "oas30":+ parameter["schema"] = {"type": "string"}+ else:+ parameter["type"] = "string"+ parameters.append(parameter)+ return parameters+++def _export_method_responses(method_obj, export_type):+ exported = {}+ for status_code, response in method_obj.get("methodResponses", {}).items():+ item = {"description": f"{status_code} response"}+ response_models = response.get("responseModels", {})+ response_parameters = response.get("responseParameters", {})++ if export_type == "oas30":+ content = {}+ for content_type, model_name in response_models.items():+ content[content_type] = {"schema": _schema_ref(model_name, export_type)}+ if content:+ item["content"] = content+ headers = {}+ for parameter_name in response_parameters:+ prefix = "method.response.header."+ if parameter_name.startswith(prefix):+ headers[parameter_name[len(prefix):]] = {"schema": {"type": "string"}}+ if headers:+ item["headers"] = headers+ else:+ if response_models:+ model_name = response_models.get("application/json") or next(iter(response_models.values()))+ item["schema"] = _schema_ref(model_name, export_type)+ headers = {}+ for parameter_name in response_parameters:+ prefix = "method.response.header."+ if parameter_name.startswith(prefix):+ headers[parameter_name[len(prefix):]] = {"type": "string"}+ if headers:+ item["headers"] = headers++ exported[str(status_code)] = item++ if not exported:+ exported["200"] = {"description": "200 response"}+ return exported+++def _export_integration(integration):+ result = {+ "type": str(integration.get("type", "aws_proxy")).lower(),+ "httpMethod": integration.get("httpMethod"),+ "uri": integration.get("uri"),+ "connectionType": integration.get("connectionType"),+ "requestParameters": integration.get("requestParameters", {}),+ "requestTemplates": integration.get("requestTemplates", {}),+ "passthroughBehavior": integration.get("passthroughBehavior"),+ "cacheNamespace": integration.get("cacheNamespace"),+ "cacheKeyParameters": integration.get("cacheKeyParameters", []),+ "timeoutInMillis": integration.get("timeoutInMillis"),+ }+ for optional_key in ("credentials", "contentHandling"):+ if integration.get(optional_key) is not None:+ result[optional_key] = integration[optional_key]++ responses = {}+ for response in integration.get("integrationResponses", {}).values():+ response_key = response.get("selectionPattern") or "default"+ exported_response = {"statusCode": response.get("statusCode")}+ for optional_key in ("responseParameters", "responseTemplates", "contentHandling"):+ value = response.get(optional_key)+ if value not in (None, {}, []):+ exported_response[optional_key] = value+ responses[response_key] = exported_response+ if responses:+ result["responses"] = responses++ return {key: value for key, value in result.items() if value is not None}+++def _export_operation(method_obj, export_type, include_integrations):+ operation = {"responses": _export_method_responses(method_obj, export_type)}+ if method_obj.get("operationName"):+ operation["operationId"] = method_obj["operationName"]++ parameters = _export_method_parameters(method_obj, export_type)+ request_models = method_obj.get("requestModels", {})+ if export_type == "oas30":+ content = {+ content_type: {"schema": _schema_ref(model_name, export_type)}+ for content_type, model_name in request_models.items()+ }+ if content:+ operation["requestBody"] = {"content": content}+ elif request_models:+ content_types = list(request_models)+ model_name = request_models.get("application/json") or request_models[content_types[0]]+ parameters.append({+ "name": "body",+ "in": "body",+ "required": False,+ "schema": _schema_ref(model_name, export_type),+ })+ operation["consumes"] = content_types++ if parameters:+ operation["parameters"] = parameters++ response_models = method_obj.get("methodResponses", {}).values()+ produced_types = {+ content_type+ for response in response_models+ for content_type in response.get("responseModels", {})+ }+ if export_type == "swagger" and produced_types:+ operation["produces"] = sorted(produced_types)++ if method_obj.get("apiKeyRequired"):+ operation["security"] = [{"api_key": []}]++ integration = method_obj.get("methodIntegration")+ if include_integrations and integration:+ operation["x-amazon-apigateway-integration"] = _export_integration(integration)+ return operation+++def _get_export_extensions(query_params):+ # API Gateway's query-string map is flattened by botocore, so+ # parameters={"extensions": "integrations"} is sent as+ # ?extensions=integrations. Keep the bracketed form as a compatibility+ # fallback for callers which serialize REST query maps that way.+ raw = query_params.get("extensions") or query_params.get("parameters[extensions]", [])+ if not raw:+ return set()+ if isinstance(raw, str):+ raw = [raw]+ return {+ extension.strip().lower()+ for value in raw+ for extension in value.split(",")+ if extension.strip()+ }+++def _build_api_export(api_id, stage_name, export_type, include_integrations):+ api = _rest_apis[api_id]+ version = api.get("version") or "1.0"+ info = {"title": api.get("name", "unnamed"), "version": version}+ if api.get("description"):+ info["description"] = api["description"]++ schemas = _export_model_schemas(api_id)+ paths = {}+ has_api_key_method = False+ for resource in _resources.get(api_id, {}).values():+ exported_methods = {}+ for http_method, method_obj in resource.get("resourceMethods", {}).items():+ method_key = (+ "x-amazon-apigateway-any-method"+ if http_method.upper() == "ANY"+ else http_method.lower()+ )+ exported_methods[method_key] = _export_operation(+ method_obj, export_type, include_integrations+ )+ has_api_key_method = has_api_key_method or bool(method_obj.get("apiKeyRequired"))+ if exported_methods:+ paths[resource.get("path", "/")] = exported_methods++ region = _rest_api_regions.get(api_id) or get_region()+ execute_url = f"https://{api_id}.execute-api.{region}.amazonaws.com/{stage_name}"+ if export_type == "oas30":+ components = {"schemas": schemas}+ if has_api_key_method:+ components["securitySchemes"] = {+ "api_key": {"type": "apiKey", "name": "x-api-key", "in": "header"}+ }+ return {+ "openapi": "3.0.1",+ "info": info,+ "servers": [{"url": execute_url}],+ "paths": paths,+ "components": components,+ }++ document = {+ "swagger": "2.0",+ "info": info,+ "host": f"{api_id}.execute-api.{region}.amazonaws.com",+ "basePath": f"/{stage_name}",+ "schemes": ["https"],+ "paths": paths,+ "definitions": schemas,+ }+ if has_api_key_method:+ document["securityDefinitions"] = {+ "api_key": {"type": "apiKey", "name": "x-api-key", "in": "header"}+ }+ return document+++def _get_export(api_id, stage_name, export_type, headers, query_params):+ if api_id not in _rest_apis:+ return _v1_error("NotFoundException", "Invalid API identifier specified", 404)+ if stage_name not in _stages_v1.get(api_id, {}):+ return _v1_error("NotFoundException", "Invalid Stage identifier specified", 404)++ export_type = export_type.lower()+ if export_type not in ("oas30", "swagger"):+ return _v1_error(+ "BadRequestException",+ "Invalid export type. Supported types are 'oas30' and 'swagger'",+ 400,+ )++ accept = (headers.get("accept") or "application/json").split(",", 1)[0].split(";", 1)[0].strip().lower()+ if accept == "application/json":+ content_type = "application/json"+ extension = "json"+ elif accept in ("application/yaml", "application/x-yaml", "text/yaml"):+ content_type = "application/yaml"+ extension = "yaml"+ else:+ return _v1_error(+ "BadRequestException",+ "Invalid Accept header. Supported values are 'application/json' and 'application/yaml'",+ 400,+ )++ export_extensions = _get_export_extensions(query_params)+ include_integrations = bool({"integrations", "apigateway"} & export_extensions)+ document = _build_api_export(api_id, stage_name, export_type, include_integrations)+ if extension == "json":+ body = json.dumps(document, ensure_ascii=False).encode("utf-8")+ else:+ body = yaml.safe_dump(document, sort_keys=False).encode("utf-8")++ api_name = re.sub(r"[^A-Za-z0-9._-]+", "-", _rest_apis[api_id].get("name", "api"))+ filename = f"{api_name}-{stage_name}-{export_type}.{extension}"+ return 200, {+ "Content-Type": content_type,+ "Content-Disposition": f'attachment; filename="{filename}"',+ }, body++# ---- Control plane: Resources ----def _get_resources(api_id, query_params):diff --git a/tests/test_apigatewayv1.py b/tests/test_apigatewayv1.pyindex ca9e0966..03353ad0 100644--- a/tests/test_apigatewayv1.py+++ b/tests/test_apigatewayv1.py@@ -8,6 +8,7 @@ import zipfilefrom urllib.parse import urlparseimport pytest+import yamlfrom botocore.exceptions import ClientErrorfrom ministack.core.responses import set_request_region@@ -436,6 +437,235 @@ def test_apigwv1_create_stage(apigw_v1):assert resp["deploymentId"] == dep_idapigw_v1.delete_rest_api(restApiId=api_id)++def test_apigwv1_get_export_oas30_json(apigw_v1):+ """GetExport returns an OpenAPI 3 document instead of matching GetStage."""+ api_id = apigw_v1.create_rest_api(+ name="v1-export-oas30",+ description="Export regression test",+ version="2026-07-22",+ )["id"]+ try:+ apigw_v1.create_model(+ restApiId=api_id,+ name="Thing",+ contentType="application/json",+ schema=json.dumps({+ "type": "object",+ "properties": {"id": {"type": "string"}},+ "required": ["id"],+ }),+ )+ root = next(+ resource+ for resource in apigw_v1.get_resources(restApiId=api_id)["items"]+ if resource["path"] == "/"+ )+ things_id = apigw_v1.create_resource(+ restApiId=api_id,+ parentId=root["id"],+ pathPart="things",+ )["id"]+ thing_id = apigw_v1.create_resource(+ restApiId=api_id,+ parentId=things_id,+ pathPart="{thingId}",+ )["id"]+ apigw_v1.put_method(+ restApiId=api_id,+ resourceId=thing_id,+ httpMethod="GET",+ authorizationType="NONE",+ operationName="GetThing",+ requestParameters={+ "method.request.path.thingId": True,+ "method.request.querystring.verbose": False,+ },+ requestModels={"application/json": "Thing"},+ )+ apigw_v1.put_method_response(+ restApiId=api_id,+ resourceId=thing_id,+ httpMethod="GET",+ statusCode="200",+ responseModels={"application/json": "Thing"},+ responseParameters={"method.response.header.X-Request-Id": False},+ )+ apigw_v1.put_integration(+ restApiId=api_id,+ resourceId=thing_id,+ httpMethod="GET",+ type="MOCK",+ integrationHttpMethod="POST",+ requestTemplates={"application/json": '{"statusCode": 200}'},+ )+ apigw_v1.put_integration_response(+ restApiId=api_id,+ resourceId=thing_id,+ httpMethod="GET",+ statusCode="200",+ )+ deployment_id = apigw_v1.create_deployment(restApiId=api_id)["id"]+ apigw_v1.create_stage(+ restApiId=api_id,+ stageName="prod",+ deploymentId=deployment_id,+ )++ response = apigw_v1.get_export(+ restApiId=api_id,+ stageName="prod",+ exportType="oas30",+ accepts="application/json",+ parameters={"extensions": "integrations"},+ )+ document = json.loads(response["body"].read())++ assert response["contentType"] == "application/json"+ assert response["contentDisposition"].endswith('v1-export-oas30-prod-oas30.json"')+ assert document["openapi"] == "3.0.1"+ assert document["info"] == {+ "title": "v1-export-oas30",+ "version": "2026-07-22",+ "description": "Export regression test",+ }+ assert document["servers"] == [{+ "url": f"https://{api_id}.execute-api.us-east-1.amazonaws.com/prod"+ }]+ assert document["components"]["schemas"]["Thing"]["required"] == ["id"]++ operation = document["paths"]["/things/{thingId}"]["get"]+ assert operation["operationId"] == "GetThing"+ assert operation["requestBody"]["content"]["application/json"]["schema"] == {+ "$ref": "#/components/schemas/Thing"+ }+ assert operation["responses"]["200"]["content"]["application/json"]["schema"] == {+ "$ref": "#/components/schemas/Thing"+ }+ assert operation["responses"]["200"]["headers"]["X-Request-Id"] == {+ "schema": {"type": "string"}+ }+ assert {parameter["name"] for parameter in operation["parameters"]} == {+ "thingId", "verbose"+ }+ assert operation["x-amazon-apigateway-integration"]["type"] == "mock"+ assert operation["x-amazon-apigateway-integration"]["responses"]["default"] == {+ "statusCode": "200"+ }+ finally:+ apigw_v1.delete_rest_api(restApiId=api_id)+++def test_apigatewayv1_get_export_swagger_yaml(apigw_v1):+ """GetExport supports Swagger 2.0 and YAML response bodies."""+ api_id = apigw_v1.create_rest_api(name="v1-export-swagger")["id"]+ try:+ apigw_v1.create_model(+ restApiId=api_id,+ name="Result",+ contentType="application/json",+ schema='{"type":"object"}',+ )+ root = next(+ resource+ for resource in apigw_v1.get_resources(restApiId=api_id)["items"]+ if resource["path"] == "/"+ )+ apigw_v1.put_method(+ restApiId=api_id,+ resourceId=root["id"],+ httpMethod="ANY",+ authorizationType="NONE",+ apiKeyRequired=True,+ requestModels={"application/json": "Result"},+ )+ apigw_v1.put_method_response(+ restApiId=api_id,+ resourceId=root["id"],+ httpMethod="ANY",+ statusCode="200",+ responseModels={"application/json": "Result"},+ )+ deployment_id = apigw_v1.create_deployment(restApiId=api_id)["id"]+ apigw_v1.create_stage(+ restApiId=api_id,+ stageName="local",+ deploymentId=deployment_id,+ )++ response = apigw_v1.get_export(+ restApiId=api_id,+ stageName="local",+ exportType="swagger",+ accepts="application/yaml",+ )+ document = yaml.safe_load(response["body"].read())++ assert response["contentType"] == "application/yaml"+ assert document["swagger"] == "2.0"+ assert document["host"] == f"{api_id}.execute-api.us-east-1.amazonaws.com"+ assert document["basePath"] == "/local"+ assert document["definitions"]["Result"] == {"type": "object"}+ assert document["securityDefinitions"]["api_key"] == {+ "type": "apiKey",+ "name": "x-api-key",+ "in": "header",+ }+ operation = document["paths"]["/"]["x-amazon-apigateway-any-method"]+ assert operation["security"] == [{"api_key": []}]+ assert operation["parameters"][0]["schema"] == {"$ref": "#/definitions/Result"}+ assert operation["responses"]["200"]["schema"] == {"$ref": "#/definitions/Result"}+ finally:+ apigw_v1.delete_rest_api(restApiId=api_id)+++def test_apigatewayv1_get_export_validates_stage_and_format(apigw_v1):+ api_id = apigw_v1.create_rest_api(name="v1-export-validation")["id"]+ try:+ with pytest.raises(ClientError) as missing_stage:+ apigw_v1.get_export(+ restApiId=api_id,+ stageName="missing",+ exportType="oas30",+ accepts="application/json",+ )+ assert missing_stage.value.response["ResponseMetadata"]["HTTPStatusCode"] == 404++ deployment_id = apigw_v1.create_deployment(restApiId=api_id)["id"]+ apigw_v1.create_stage(+ restApiId=api_id,+ stageName="prod",+ deploymentId=deployment_id,+ )+ empty_export = apigw_v1.get_export(+ restApiId=api_id,+ stageName="prod",+ exportType="oas30",+ accepts="application/json",+ )+ assert json.loads(empty_export["body"].read())["components"]["schemas"] == {}++ with pytest.raises(ClientError) as invalid_export_type:+ apigw_v1.get_export(+ restApiId=api_id,+ stageName="prod",+ exportType="invalid",+ accepts="application/json",+ )+ assert invalid_export_type.value.response["ResponseMetadata"]["HTTPStatusCode"] == 400++ with pytest.raises(ClientError) as invalid_accept:+ apigw_v1.get_export(+ restApiId=api_id,+ stageName="prod",+ exportType="oas30",+ accepts="text/plain",+ )+ assert invalid_accept.value.response["ResponseMetadata"]["HTTPStatusCode"] == 400+ finally:+ apigw_v1.delete_rest_api(restApiId=api_id)++def test_apigwv1_update_stage(apigw_v1):"""UpdateStage (PATCH) updates stage variables."""api_id = apigw_v1.create_rest_api(name="v1-stage-update")["id"]