create-rest-controller
/create-rest-controller
Tworzy lub aktualizuje kontroler REST Spring dla jednego portu wejściowego, z testem @WebMvcTest, specyfikacją OpenAPI i klientem frontendu.
- Autor
- Miragon ↗
- Repozytorium
- process-engine-blueprints ↗
- Licencja
- MIT
- Ostatnia zmiana repozytorium
- 07.11.2026
Ocena i bezpieczeństwo
- Pliki w paczce
- 1
- Skrypty
- 0
- Komentarze HTML
- 0
- Adresy URL w SKILL.md
- 0
Brak sygnałów. Repozytorium zmienione 07.11.2026, bez odwołań do wycofanych modeli i API.
MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.
Co robi i kiedy
Tworzy lub aktualizuje kontroler REST Spring dla jednego portu wejściowego, z testem @WebMvcTest, specyfikacją OpenAPI i klientem frontendu.
Argumenty
/create-rest-controller [UseCase-or-Query port] [http-verb] [path]
Oryginalny opis (EN)
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.
Jak działa
- Production pattern
- Test pattern
- Instructions
Podgląd SKILL.md
---
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.
Wersje
| Repozytorium | Wynik | Licencja |
|---|---|---|
| Ta strona · 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 |
Migawka bazy z 13.11.2026 · wersja paczki 6b6b53c4de24 (skrót SHA-256 całej paczki)
Pobrania w ostatnich 30 dniach: 0 · ranking
Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.
Podobne skille
- 100unit-test-controller-layer
Dostarcza wzorce testów jednostkowych kontrolerów REST z MockMvc i @WebMvcTest: mapowanie żądań i odpowiedzi, walidacja, obsługa wyjątków i kody statusu HTTP. - 100api-first
Tworzy i implementuje endpointy REST lub zasoby w projekcie Spring Boot, zwłaszcza z fragmentu lub specyfikacji OpenAPI: kontrolery, CRUD oraz operacje POST, GET, PUT, PATCH i DELETE. - 100spring-boot-conventions
Ujednolica kod Spring Boot w Javie, czyli kontrolery, serwisy, DTO, stronicowanie i format odpowiedzi błędów. - 100api-scaffolder
Tworzy nowy endpoint API z trasą, handlerem, walidacją, sprawdzeniem uprawnień, testami i OpenAPI, zgodnie z konwencjami projektu. - 100302-frameworks-spring-boot-rest
Projektuje i sprawdza REST API w Spring Boot: metody, kody statusu, DTO, wersjonowanie, stronicowanie, walidację i OpenAPI. - 100spring-boot-openapi-documentation
Generuje dokumentację REST API w SpringDoc OpenAPI 3.0 i Swagger UI dla Spring Boot 3.x: adnotacje, dokumentacja bezpieczeństwa, przykłady i schematy.