[ako]

Refs #1234 (mendixlabs#280). This PR does not close the issue: it carries the design and Phase 0 only.

1. Proposal: docs/11-proposals/PROPOSAL_openapi_response_entities.md (draft)

The OpenAPI import wires every JSON response as raw Response: json. The proposal adds an opt-in GenerateEntities: Yes that:

• creates non-persistent entities from the response schemas;
• writes each operation's response as an inline Response: mapping. mxcli already writes this form (Rest$ImplicitMappingResponseHandling, round-tripped since A recursive microflow cannot be created in one statement (exec: microflow not found; check passes) #843), so no JSON-structure or import-mapping documents are needed.

The work is phased. Array roots and nested arrays are blocked on a Studio Pro reference project; the proposal's open questions list what that project needs to show.

2. Phase 0 (this PR's code)

Symptom, measured on the reporter's spec (petstore.swagger.io/v2/swagger.json, Swagger 2.0): describe contract operation from openapi and the create path reported success, but produced:

• BaseUrl: '';
• no request bodies;
• Response: none on every operation;
• no warning at all.

Cause: openapi.ParseSpec unmarshals into OpenAPI 3 types only, and a 2.0 document parses cleanly into an empty contract.

Fix:

• A document with a swagger field is refused with a conversion hint (npx swagger2openapi / converter.swagger.io). Full 2.0 support is Phase 4 of the proposal.
• The rest-client skill and the docs-site now say that the import returns JSON responses as strings, and show how to wire Response: mapping Entity { … }. The reporter's agent wrote entities and import mappings, then left every operation at Response: JSON.

Evidence:

• Test first: TestParseSpec_RefusesSwagger2 (JSON and YAML). It failed before the fix (a Swagger 2.0 document was accepted (1 paths)).
• TestParseSpec_AcceptsOpenAPI3 is the control: 3.0 and 3.1 still parse and convert.
• Real specs: Petstore 2.0 is now refused with the message; Petstore 3.0 output is unchanged.
• Repro mdl-examples/bug-tests/280-openapi-swagger2-refused.mdl with fixture mdl-examples/openapi-local-specs/petstore-swagger2.json. It is a plain .mdl because mxcli check cannot see an execution-time refusal; the unit test pins the guard.
• make build, make lint, make test, make check-skill-mdl, make check-skill-index and make check-findings pass. Finding recorded. main is merged in, re-checked after the merge.

---

Generated by Claude Code