Merge pull request #286 from mendixlabs/merge/268-openapi-import

feat: import consumed REST client from OpenAPI 3.0 spec

Author: ako

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

@@ -2,20 +2,60 @@
 
 Use this skill when integrating with external REST APIs from Mendix.
 
-## Two Approaches
+## Three Approaches
 
-Mendix offers two ways to call REST APIs from microflows. Choose based on the use case:
+Mendix offers three ways to call REST APIs from microflows. Choose based on the use case:
 
 | Approach | When to Use | Artifacts |
 |----------|-------------|-----------|
-| **REST Client + SEND REST REQUEST** | Structured APIs with multiple operations, reusable across microflows, Studio Pro UI support | REST client document + microflow |
+| **OpenAPI import** | API has an OpenAPI 3.0 spec — auto-generate from the spec | REST client document generated in one command |
+| **REST Client (manual)** | No spec available, or need fine-grained control | REST client document + microflow |
 | **REST CALL (inline)** | One-off calls, quick prototyping, dynamic URLs, low-level HTTP control | Microflow only |
 
-Both can be combined with **Data Transformers** (Mendix 11.9+) and **Import/Export Mappings** to map between JSON and entities.
+Both REST Client approaches can be combined with **Data Transformers** (Mendix 11.9+) and **Import/Export Mappings** to map between JSON and entities.
 
 ---
 
-## Approach 1: REST Client (Recommended)
+## Approach 0: OpenAPI Import (Fastest)
+
+If the API has an OpenAPI 3.0 spec (JSON or YAML), generate the REST client in one command:
+
+```sql
+-- From a local file (relative to the .mpr file)
+create or modify rest client CapitalModule.CapitalAPI (
+  OpenAPI: 'specs/capital.json'
+);
+
+-- From a URL
+create or modify rest client PetStoreModule.PetStoreAPI (
+  OpenAPI: 'https://petstore3.swagger.io/api/v3/openapi.json'
+);
+
+-- Override the base URL (replaces servers[0].url from the spec)
+create or modify rest client PetStoreModule.PetStoreStaging (
+  OpenAPI: 'https://petstore3.swagger.io/api/v3/openapi.json',
+  BaseUrl: 'https://staging.petstore.example.com/api/v3'
+);
+```
+
+This generates:
+- All operations with correct HTTP method, path, parameters, headers, body, and response type
+- Resource groups based on OpenAPI `tags`
+- Basic auth if the spec declares it at the top level
+- The spec stored inside the document for Studio Pro parity
+
+`BaseUrl` is optional. When omitted, `servers[0].url` from the spec is used. When provided, it overrides that value — useful when the spec points at production but you need to import against staging or a different version.
+
+**Preview without writing:**
+```sql
+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.
+
+---
+
+## Approach 1: REST Client (Manual)
 
 Define the API once as a REST client document, then call its operations from microflows.
 

CHANGELOG.md

@@ -15,6 +15,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 - **Shared URL utilities** — `internal/pathutil` package with `NormalizeURL()`, `URIToPath()`, and `PathFromURL()` for reuse across components
 - **@anchor sequence flow annotation** — optional `@anchor(from: X, to: Y)` annotation on microflow statements that pins the side of the activity box a SequenceFlow attaches to (top / right / bottom / left). Split (`if`) statements support the combined form `@anchor(to: X, true: (from: ..., to: ...), false: (from: ..., to: ...))` so the incoming and per-branch outgoing anchors survive describe → exec round-trip. When omitted, the builder derives the anchor from the visual flow direction (existing behaviour is unchanged). Keeps the flow diagram stable across patches when an agent-generated microflow is applied back to a project
 - **@anchor loop form** — `LOOP`/`WHILE` statements accept `@anchor(iterator: (...), tail: (...))` in the grammar so authoring tools can forward-propagate the intent. Today the builder deliberately does not translate those into SequenceFlows: Studio Pro rejects edges between a `LoopedActivity` and its body statements with CE0709 ("Sequence flow is not accepted by origin or destination"), since the iterator icon is drawn implicitly from the loop geometry. Reserving the grammar slot keeps scripts forward-compatible with any future Mendix capability
+- **OpenAPI import for REST clients** — `CREATE REST CLIENT` now accepts `OpenAPI: 'path/or/url'` to auto-generate a consumed REST service document from an OpenAPI 3.0 spec (JSON or YAML); operations, path/query parameters, request bodies, response types, resource groups (tags), and Basic auth are derived automatically; spec content is stored in `OpenApiFile` for Studio Pro parity (#207)
+- **DESCRIBE CONTRACT OPERATION FROM OPENAPI** — Preview what would be generated from an OpenAPI spec without writing to the project
 
 ### Changed