Skip to content
Skills Library
Programming · Building & coding

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.

Licence
MIT
Last repository change
07.11.2026

Assessment and security

90/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content25 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 07.11.2026, without references to retired models or APIs.

Licence

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

  1. Production pattern
  2. Test pattern
  3. Instructions
Original SKILL.md headings · 61 lines, 491 words
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

RepositoryScoreLicence
This page · Miragon/process-engine-blueprints90MIT
Miragon/process-engine-blueprints100MIT
Miragon/process-engine-blueprints90MIT
Miragon/process-engine-blueprints90MIT
Miragon/process-engine-blueprints90MIT
Miragon/process-engine-blueprints90MIT
Miragon/process-engine-blueprints90MIT

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.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.