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, the regenerated frontend client 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, the regenerated frontend client 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, the regenerated frontend client 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, the regenerated frontend client 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-0004](../../../docs/adr/0004-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, and orval names the client hook after it. Only paths under `/api/**`
(`springdoc.paths-to-match`) reach the spec.
- Errors become problem details in `GlobalExceptionConfiguration`: `IllegalArgumentException` → 400,
`IllegalStateException` → 404, `MismatchingMessageCorrelationException` → 409 (the case has moved
on). Throw those from the domain or the service; 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 409 mapping; 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.
Then regenerate the frontend client with skill `sync-api-client`.
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 numbered folder.
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 6b6b53c4de24 (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,… - 100spring-boot-openapi-documentation
Provides patterns to generate comprehensive REST API documentation using SpringDoc OpenAPI 3.0 and Swagger UI in Spring Boot 3.x applications. Use when setting up API documentation, configuring Swagger UI, adding OpenAPI annotations, implementing security documentation, or…