OpenAPI response entities: proposal + Phase 0 (refuse Swagger 2.0, document response wiring)

.claude/skills/fix-issue/findings/mdl-other/2026-10-21-openapi-swagger2-parses-to-empty-contract.json

@@ -0,0 +1 @@
+{"area": "mdl/openapi", "date": "2026-10-21", "symptom": "`create consumed rest service … ( OpenAPI: '…swagger.json' )` / `describe contract operation from openapi` on a Swagger 2.0 spec reports success and produces `BaseUrl: ''`, no request bodies and `Response: none` on every operation, with no warning", "cause": "`openapi.ParseSpec` unmarshals into OpenAPI 3 types only; a 2.0 document has none of those fields where they are expected (host/basePath, response `schema`, `in: body`, `definitions`), so unmarshalling succeeds and yields an empty contract", "file": "`mdl/openapi/parser.go` (`Spec.Swagger`, `ParseSpec`)", "insight": "**A permissive unmarshal is a silent format detector that always answers yes**: JSON/YAML into a struct ignores every unknown field, so the wrong document VERSION parses cleanly and degrades into defaults. Read the version discriminator (`swagger` vs `openapi`) before trusting the parse. The reported issue (#280, missing response entities) hid this: the reporter's spec was 2.0, so even response TYPES were lost, which nobody had noticed because the doctype test only ever used the 3.0 Petstore. When testing an importer, run the reporter's actual input before reasoning about the feature gap. Refusal with a conversion hint (swagger2openapi / converter.swagger.io) beats a half-import; full 2.0 normalisation is Phase 4 of PROPOSAL_openapi_response_entities.md. Test `TestParseSpec_RefusesSwagger2` (JSON and YAML) with an OpenAPI 3.0/3.1 control", "refs": ["mendixlabs/mxcli#280", "ako/mxcli#1234"]}

.claude/skills/mendix/rest-client/SKILL.md

@@ -11,15 +11,15 @@ description: "Call external REST APIs from Mendix — the three approaches (inli
 | lines | section |
 |---|---|
 | 29-44 | Three Approaches |
-| 45-91 | Approach 0: OpenAPI Import (Fastest) |
-| 92-318 | Approach 1: REST Client (Manual) |
-| 319-364 | Approach 2: REST CALL (Inline HTTP) |
-| 365-397 | Data Transformers (JSLT — Mendix 11.9+) |
-| 398-435 | JSON Structures & Mappings |
-| 436-507 | Complete Pipeline Example |
-| 508-538 | Published REST: Authentication Parameters |
-| 539-548 | Mendix Validation Rules |
-| 549-569 | BSON Types Reference |
+| 45-110 | Approach 0: OpenAPI Import (Fastest) |
+| 111-337 | Approach 1: REST Client (Manual) |
+| 338-383 | Approach 2: REST CALL (Inline HTTP) |
+| 384-416 | Data Transformers (JSLT — Mendix 11.9+) |
+| 417-454 | JSON Structures & Mappings |
+| 455-526 | Complete Pipeline Example |
+| 527-557 | Published REST: Authentication Parameters |
+| 558-567 | Mendix Validation Rules |
+| 568-588 | BSON Types Reference |
 
 <!-- /skill-index -->
 # REST Integration Skill
@@ -44,7 +44,10 @@ No API to call against yet — or one you would rather not depend on while build
 
 ## Approach 0: OpenAPI Import (Fastest)
 
-If the API has an OpenAPI 3.0 spec (JSON or YAML), generate the REST client in one command:
+If the API has an OpenAPI 3.x spec (JSON or YAML), generate the REST client in one command.
+A **Swagger 2.0** spec (`"swagger": "2.0"`, e.g. `petstore.swagger.io/v2/swagger.json`) is
+refused — convert it first (`npx swagger2openapi in.json -o out.json`, or
+https://converter.swagger.io) and import the converted file:
 
 ```sql
 mdl 1;
@@ -87,6 +90,22 @@ describe contract operation from openapi 'specs/capital.json';
 
 **After import:** the REST client is ready to use with `SEND REST REQUEST`. No manual operation definition needed.
 
+**But every JSON response is imported as `response: json` — a raw string, not objects.** The
+import does not generate response entities yet (ako/mxcli#1234). To get objects, create the
+non-persistent entities yourself and give the operations you call a mapping (see *Response
+Types* below):
+
+```sql
+mdl 1;
+alter consumed rest service PetStoreModule.PetStoreAPI
+  modify operation getPetById (
+    response: mapping PetStoreModule.Pet { Id = id, Name = name }
+  );
+```
+
+Writing the entities and an import-mapping document but leaving the operation at
+`response: json` is the common mistake: nothing uses the mapping, and nothing reports that.
+
 ---
 
 ## Approach 1: REST Client (Manual)

docs-site/src/examples/rest-integration.md

@@ -219,7 +219,9 @@ CREATE IMPORT MAPPING Integration.IMM_Order
 
 ### From an OpenAPI Spec (Recommended)
 
-If the API has an OpenAPI 3.0 spec (JSON or YAML), generate the REST client in one command:
+If the API has an OpenAPI 3.x spec (JSON or YAML), generate the REST client in one command.
+A Swagger 2.0 spec is refused; convert it to OpenAPI 3 first (for example
+`npx swagger2openapi swagger.json -o openapi.json`) and import the converted file.
 
 ```sql
 mdl 1;
@@ -236,6 +238,10 @@ CREATE OR MODIFY CONSUMED REST SERVICE PetStoreModule.PetStoreAPI (
 
 Operations, path/query parameters, request bodies, response types, resource groups (from `tags`), and Basic auth are all derived automatically from the spec.
 
+JSON responses are imported as `Response: JSON` (a string). The import does not yet create
+entities for them: to get objects, create non-persistent entities and give the operation a
+`Response: MAPPING Module.Entity { … }`, as shown under *Manual Definition* below.
+
 **Preview without writing:**
 ```sql
 DESCRIBE CONTRACT OPERATION FROM OPENAPI 'specs/capital.json';

docs-site/src/reference/capabilities.md

@@ -84,7 +84,7 @@ Everything mxcli can do, organized by use case.
 | Capability | Command | Status |
 |---|---|---|
 | REST clients | `CREATE CONSUMED REST SERVICE` | Consumed REST services |
-| OpenAPI import | `CREATE CONSUMED REST SERVICE (OpenAPI: '...')` | Generate REST client from OpenAPI 3.0 spec |
+| OpenAPI import | `CREATE CONSUMED REST SERVICE (OpenAPI: '...')` | Generate REST client from an OpenAPI 3.x spec (Swagger 2.0 refused; responses imported as JSON, no entities yet) |
 | Business events | `CREATE BUSINESS EVENT SERVICE` | Event definitions |
 | Database connections | `CREATE DATABASE CONNECTION` | External SQL |
 | OData services | `LIST CONSUMED ODATA SERVICES/SERVICES` | Read-only browsing |