create-rest-controller
/create-rest-controller
Create or update one Spring @RestController (inbound adapter) for one inbound port, with its request types, an @Operation(operationId) and its @WebMvcTest, then carry the change through the re-exported openapi/openapi.json and a Bruno request. Use when the user asks to create a REST controller, add an endpoint, or expose a use case over REST.
- Author
- Miragon ↗
- Repository
- process-engine-blueprints ↗
- Licence
- MIT
- Last repository change
- 07.11.2026
Assessment and security
- Files in this package
- 1
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 07.11.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
Create or update one Spring @RestController (inbound adapter) for one inbound port, with its request types, an @Operation(operationId) and its @WebMvcTest, then carry the change through the re-exported openapi/openapi.json and a Bruno request. Use when the user asks to create a REST controller, add an endpoint, or expose a use case over REST.
Arguments
/create-rest-controller [UseCase-or-Query port] [http-verb] [path]
Original author description
Create or update one Spring @RestController (inbound adapter) for one inbound port, with its request types, an @Operation(operationId) and its @WebMvcTest, then carry the change through the re-exported openapi/openapi.json and a Bruno request. Use when the user asks to create a REST controller, add an endpoint, or expose a use case over REST.
How it works
- Production pattern
- Test pattern
- Instructions
SKILL.md preview
---
name: create-rest-controller
argument-hint: "[UseCase-or-Query port] [http-verb] [path]"
description: "Create or update one Spring @RestController (inbound adapter) for one inbound port, with its request types, an @Operation(operationId) and its @WebMvcTest, then carry the change through the re-exported openapi/openapi.json and a Bruno request. Use when the user asks to create a REST controller, add an endpoint, or expose a use case over REST."
allowed-tools: Read, Write, Edit, Glob, Grep, Bash, Skill
---
# Skill: create-rest-controller
One endpoint per class in `adapter/inbound/rest/` (package `io.miragon.blueprint` under
`service/app/src/main/`), its test next to it in the test tree. The architecture rules are in
`AGENTS.md`; the contract rules in [ADR-0003](../../../docs/adr/0003-openapi-as-the-checked-in-contract.md).
## Production pattern
Copy the shape of the existing controllers instead of inventing one:
| Case | Reference |
|---|---|
| creating a case | `SubmitLeasingRequestController`: `POST /api/bike-leasing`, 200 with the new id |
| a command without a body (path variable only) | `SignContractController` |
| a command with a request body | `SelectAlternativeController` (nested `AlternativeDecisionInput`) |
| a single read | `GetLeasingApplicationController` (nested `LeasingApplicationDto`) |
| a list or page read | `ListLeasingApplicationsController` |
- **One inbound port** as the only constructor parameter; a read and a command are two controllers.
- Commands on a case are `POST /api/bike-leasing/{applicationId}/<action>` and answer **202**,
because the engine continues asynchronously. Reads are `GET` with a `*Query` and a nested `*Dto`; a
single read answers `ResponseEntity.notFound()` when the query finds nothing.
- Wrap every request field that has a domain value object (`ApplicationId.of(…)`, `BikeId(…)`) before
calling the port; plain values pass through.
- **Always set `@Operation(operationId = "…")`** (camelCase). Without it springdoc falls back to the
method name (`byId`, `list`) as the operationId. Only paths under `/api/**`
(`springdoc.paths-to-match`) reach the spec.
- Errors become problem details in `GlobalExceptionConfiguration`: `IllegalArgumentException` → 400,
`IllegalStateException` → 404, `NoSuchElementException` → 409 (the user task is no longer open, the
case has moved on). Throw those from the domain, the service or the process adapter; don't catch
them in the controller.
## Test pattern
`@WebMvcTest(<Controller>.class)` with the port mocked, one test per outcome (references:
`SelectAlternativeControllerTest`, `GetLeasingApplicationControllerTest`):
- the success status with the **exact** port call, built from the domain value objects, then the
strict check (`confirmVerified` / `verifyNoMoreInteractions`);
- each invalid input → 400, and the port is **not** called;
- for a read, every DTO field in the body (nothing else notices a mapping no test reads) and
the not-found case → 404.
`GlobalExceptionConfigurationTest` covers the 404 and 409 mappings; the 400 is asserted in the controller
tests. Given/when/then comments, as in the existing tests.
## Instructions
1. **Resolve the port** from `$ARGUMENTS`, else list `application/port/inbound/` and ask. If the port
does not exist yet, create it and its service first (a unit test with the outbound ports mocked).
2. **Agree verb, path and status codes** with the user.
3. **Write the test first**, then the controller; for an existing file add only what is missing. Run
it by name (`AGENTS.md` → Verify After Each Task).
4. **Carry the contract through:** regenerate `openapi/openapi.json` with the `OpenApiSpecExportTest`
(`AGENTS.md` → Build Commands) and review `git diff -- openapi/openapi.json`: the new path with its
operationId and schemas. Never hand-edit the file.
5. **Add the request to `bruno/`**: in the scenario folder of the flow, numbered in order, with
assertions on the status and the body; a new flow gets a new folder and a row in
`bruno/README.md`.
Versions
| Repository | Score | Licence |
|---|---|---|
| This page · Miragon/process-engine-blueprints | 90 | MIT |
| Miragon/process-engine-blueprints | 100 | MIT |
| Miragon/process-engine-blueprints | 90 | MIT |
| Miragon/process-engine-blueprints | 90 | MIT |
| Miragon/process-engine-blueprints | 90 | MIT |
| Miragon/process-engine-blueprints | 90 | MIT |
| Miragon/process-engine-blueprints | 90 | MIT |
Database snapshot: 13.11.2026 · package version 09e78ca1c2c3 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100unit-test-controller-layer
Provides patterns for unit testing REST controllers using MockMvc and @WebMvcTest. Generates controller tests that validates request/response mapping, validation, exception handling, and HTTP status codes. Use when testing web layer endpoints in isolation for API endpoint… - 100api-first
Use when the user wants to scaffold or implement a REST endpoint or resource in a Spring Boot project, especially from an OpenAPI snippet or spec: create endpoint, add API, add CRUD, generate controller, or implement POST/GET/PUT/PATCH/DELETE on a resource. - 100spring-boot-conventions
House conventions for writing Spring Boot (Java) backend code, covering controllers, services, DTOs, pagination, error responses. Use whenever the user asks to write, add, refactor, or review a Spring Boot controller, service, repository, DTO, endpoint, or REST API in Java.… - 100api-scaffolder
Scaffold a new API endpoint (route, handler, input validation, auth check, tests and OpenAPI docs) that follows the project's existing structure and conventions. Use when the user asks to add a REST or HTTP endpoint, create a new route or controller, wire up a CRUD resource, or… - 100302-frameworks-spring-boot-rest
Use when you need to design, review, or improve REST APIs with Spring Boot — including HTTP methods, resource URIs, status codes, DTOs, versioning, deprecation and sunset headers, content negotiation (JSON and vendor media types), ISO-8601 instants in DTOs,… - 100api-contract-sync
Keep API code, OpenAPI, Bruno, Gherkin, mocks and client types in step. Use when an endpoint, DTO, payload, status code, query parameter or auth rule changes.