Spring Boot Web
Own the Spring MVC/Servlet boundary of a Boot 4.x application: actual HTTP behavior, faithful consumer documentation and bounded request resource use. Use for implementation, documentation, diagnosis or review; a findings-only review does not authorize edits. Keep a focused endpoint or documentation change within its existing application boundary. For an authorized whole-service task, compose persistence, access policy and Boot operations with their owners; this skill's specialization must not shrink that task to a disposable controller demo. Do not turn a sound MVC application into WebFlux or implement an identity provider to satisfy this skill. Use of WebClient alone does not identify the server stack.
Use Java 25 as the authoring and example baseline. If the target project uses another release, state the compatibility difference and respect its constraints unless migration is authorized. A skill activation does not silently upgrade the application.
For OpenAPI/springdoc implementation and documentation, follow the current user-designated Customer reference and the portable Customer pattern. The complete source index supplies all 41 production Java files, seven test classes, build and configuration from the approved working tree of C:/git/customer. It includes modified and untracked files and excludes removed modules. Use these complete files when reproducing the pattern; a synthetic example or selected annotation excerpt cannot replace them. The original checkout is not a runtime prerequisite. Preserve its separation of API interface, implementing controller, DTOs, documentation annotations/examples, global and feature customizers, and specific/global/servlet error handling. Read coverage and consumer content before claiming an API is fully documented. Adapt business names and rules only from the target's evidence; do not import Customer's business rules or supporting persistence as a new architecture.
Use the official Spring Boot documentation for the resolved version as the starting authority for MVC auto-configuration and properties. When the HTTP contract crosses security, also consult the matching Spring Security reference; for persistence behavior behind an endpoint, route to JPA expertise with the matching Spring Data JPA reference. Do not transplant a rolling reference's APIs into a different project release.
Establish the actual contract
Inspect only evidence that can change the decision:
- Read the request, build/toolchain, resolved Boot/Framework/Jackson/Servlet/server versions, security configuration, documentation build, ADRs and existing tests. This skill targets Boot 4.x only; identifying Boot 3 is a compatibility boundary, not permission to upgrade it. Fixture versions are in the fixture guide; one tested pair does not prove all 4.x pairs.
- Inspect controller mappings, inherited interfaces, JSON names/views/custom serializers, converters, validation, advice, filters, context path and ingress rules. Identify consumers and compatibility constraints. Distinguish explicit requirements, consistent conventions, isolated patterns and assumptions. Do not infer organization policy from one controller. When the user supplies an architectural reference, trace its HTTP-to-use-case flow and preserve the intended naming and mapping roles; see inputs and outputs.
- For failures, retain the sanitized request, response, trace and dispatch boundary; for capacity, inspect the active executor and measured wait/CPU/queue/pool behavior. A plausible cause is a hypothesis until evidence discriminates it from alternatives.
- Separate established decisions from reversible assumptions and unresolved contract choices. Resolve repository evidence before asking; group only questions that change behavior, such as PATCH null semantics, trusted proxies, public error detail or consumer compatibility. Include the evidence and a conditional recommendation. Continue independent work while those answers are pending; do not invent access policies or commercial quotas.
For each material concern, apply what the contract needs, reuse an adequate existing control, clarify a consequential unknown, defer work outside the request with a reason/revisit condition, or omit a feature with no demonstrated need. Record only decisions useful to maintenance. For example, inspect a partner API's consumers and gateway policy before proposing a limiter; ask which contractual quota applies only if that information is still missing. An internal field-error correction normally reuses the current advice, tests and documentation pipeline.
For a new business API, establish its consumer flow before choosing a teaching fixture: which operations are needed, which records must survive restart, which invariants span replicas, who may read or mutate, and how consumers traverse a growing collection. Treat business registrations as durable unless the user explicitly requests disposable data. Choose an access policy from the intended actors; missing identity configuration is an unresolved dependency, not permission to expose mutations publicly. Preserve intentionally public operations when that is the agreed contract. Read the service acceptance guidance for whole-service implementation; use only affected checks for a narrow endpoint change.
Preserve package structure, naming and adequate representations. Use single-constructor
or bean-method parameter injection in new code, without @Autowired. Register a component
once. Add a WebMvcConfigurer for an extension; adding @EnableWebMvc takes over MVC
configuration and requires accounting for Boot behavior that no longer applies.
Inspect the resolved Jackson generation and extension APIs; do not transplant Jackson 2
configuration or Boot 3 test imports into a Boot 4 project by resemblance.
Prefer ResponseEntity<ConcreteDto> for new or changed REST controller methods, including
ResponseEntity<Void> for a bodyless 204 and a concrete response DTO for pages. Make status
and headers explicit; avoid raw/wildcard response types. This convention belongs at the HTTP
boundary, not services or repositories. Preserve specialized streaming signatures and
framework override types where their contracts require them.
Start with Boot's MVC configuration, ordinary request/response DTOs and Jakarta validation.
If standard MVC Problem Details satisfy the consumer, use spring.mvc.problemdetails.enabled=true;
add ResponseEntityExceptionHandler overrides only for an actual representation requirement,
such as a field-violation extension. Reuse the project's error policy when adequate. An example
is evidence for its stated contract, not a checklist of infrastructure to copy: a plain public
endpoint does not need a synthetic token issuer, a generic field-name translator or a new body
buffering layer. Custom code needs a concrete contract that the existing facilities cannot meet.
Keep shared errors and sanitized unexpected failures in a global advice, such as a
GlobalExceptionHandler; introduce local or narrowly scoped handlers only for controller/module
semantics that differ. Preserve the common response contract and verify handler precedence;
see error ownership.
Preserve Customer's independent business exceptions; do not add a shared base absent from
that source. In another project, retain an established typed code/context contract and
relevant identifiers. Keep Spring/HTTP mapping in the API layer;
shared handling must distinguish missing resources, conflicts and unexpected defects.
Make the HTTP boundary explicit
| Decision | Choose using these conditions | Verify the actual boundary |
|---|---|---|
| Mappings and binding | Match method/path, content types, query/header/cookie semantics and conversion. Preserve an established versioning scheme; neither URL versioning nor a verb choice follows from style alone. | Missing body/parameter, malformed JSON, conversion failure, unsupported media type and unacceptable response type. |
| Public DTOs | Separate accepted data from entity/internal state. Choose create, replacement and patch contracts deliberately; do not let writable IDs, ownership or server fields slip through generic binding. | JSON names, token types/coercion, dates/precision/enums, unknown-property policy, optional/nested values and read/write exposure with the real mapper. |
| Validation | Transport shape belongs at MVC; domain invariants must also hold for non-HTTP callers. Inspect argument versus method validation and the role of class-level @Validated. |
Both MethodArgumentNotValidException and HandlerMethodValidationException where applicable, global errors and multiple violations for one field. |
| Error ownership | Controller advice handles MVC paths, not every failure before dispatch. Locate security, container, filter and async errors separately. Preserve an established error envelope or intentionally implement ProblemDetail. | Status/media type/body at the origin; never leak stack traces, rejected secrets or internal SQL. Aggregate duplicate field errors without a duplicate-key exception. |
| Creation and reads | Use public response DTOs, correct success status and Location when the contract supplies one. Preserve absent/null/default semantics and caching/conditional requests if present. | Create then follow Location behind the intended context/proxy; no body for 204; check headers and serialized output. |
| Pagination/filtering | Bound page size and sort fields, use a stable ordering and explicit public representation. A framework Page's incidental JSON is not automatically the consumer contract. | Empty/last pages, invalid bounds and stable tie ordering; hand query cardinality to persistence expertise. |
| Pipeline extension | Filter for request/response wrapping and pre-dispatch work; interceptor for handler-aware concerns; resolver/converter for binding; advice for controller-wide handling. | Ordering, error/async dispatch, ownership and cleanup. Authentication belongs in the security chain, not an interceptor. |
Read MVC behavior and tests for binding, semantic validation, errors, security integration, bounded pagination, conditional HTTP requests, streaming, uploads or test selection. Separate protocol semantics from resource-naming preferences; do not turn every business action into CRUD or equate HTTP JSON with all REST constraints. A uniqueness precheck is not a concurrency guarantee: coordinate a database constraint and map only its known conflict; do not translate every integrity exception into HTTP 409.
For a new externally callable API, establish request limits; for an existing API, inspect and preserve adequate controls. Bound JSON before binding: body bytes, parser depth/ token sizes and DTO constraints are different controls. Form/multipart limits do not cap JSON bodies. Read request bounds for layer selection, unknown-length bodies and adversarial checks. Validation error paths must use the public input names, including nested JSON properties and header/query aliases; see the MVC reference.
For an OpenAPI delivery where many operations share an established 400/500 contract, reusable response components can avoid duplicate declarations. Prefer correct springdoc inference or existing annotations; use a global customizer when a real cross-group policy needs it. Customer's customizer publishes its conditional catalog on every operation; reproduce that policy with its conditions, preserve operation-specific responses/examples, and verify default plus grouped documents. Register referenced error schemas explicitly; do not depend on one controller annotation making a shared schema reachable. Keep unexpected failures observable through the project's safe logging/tracing policy while returning sanitized 500 responses.
Deliver the consumer contract through the chosen documentation
Identify the authoritative contract and existing publication pipeline before adding tooling. For a new API, changed consumers or a documentation-tool decision, read contract ownership and delivery. Choose maintained OpenAPI, code-generated OpenAPI, test-produced REST Docs or the existing usage guide from actual consumer needs. OpenAPI descriptions, interactive UI and a usage guide are different deliverables. Preserve an adequate existing choice for a narrow change; no new dependency is required simply because a controller changed.
When OpenAPI/springdoc is selected or already owns generation, read springdoc/OpenAPI. Document all in-scope operations and public properties, including optional and nested fields, with meaningful semantics and usable examples. Apply the same coverage obligation to an agreed REST Docs/guide delivery; each approach proves only its exercised contracts. Applicable features depend on the API, not whether a specification marks a field mandatory.
For a whole-API request, reconcile every operation, representation and polymorphic variant with the coverage inventory in that reference; a representative controller is not the delivery. Trace validation and normalization through the use case too: creation, replacement, PATCH and responses can have different constraints. Resolve contradictions between source, tests and prose before promoting a reference project's behavior into a reusable rule. For a request to use all Swagger resources, assess every feature family for applicability; implement the applicable ones and identify unsupported or unresolved contracts explicitly. Ask about missing consumer guarantees after inspection, without inventing them or treating unanswered questions as approval to choose a behavior.
Essential decisions remain these:
- Inventoried path/method/media-type variants and public input/output properties define coverage. An annotation count, green parser or attractive UI cannot establish 100%.
- Required parameter, required body, required property, non-null, non-empty and a runtime default are different contracts. Create and PATCH often require different schemas.
@Schemadescribes; it does not validate, hide serialized data or enforce access. Security annotations describe authentication requirements; they do not secure routes.- Documented responses must match controller, advice and filter behavior. Include success, applicable errors and headers, without inventing a body for 204 or a universal error shape.
- For OpenAPI, generate/validate every published group and its examples against the chosen dialect and HTTP behavior; exercise Swagger UI when supplied. For REST Docs, execute the documenting tests and render the assembled guide, checking optional/variant coverage. Record limitations; an unexercised contract is not verified by an attractive publication.
Read schemas and examples when matching OpenAPI schemas to DTOs, PATCH, polymorphism, multipart or examples. Read springdoc integration and customization for inherited API interfaces, composed annotations, asynchronous wrappers, shared error catalogs or lost schema metadata. Read Swagger UI and publication when configuring UI, groups, security, external exposure, branding, proxy URLs or generation in CI. These references separate format, generator, runtime and rendering limitations.
Capacity follows workload and resource ownership
Read capacity and lifecycle for Tomcat, pools, virtual threads, timeouts, HTTP/2, compression, quotas, overload or async request changes. Reuse adequate gateway enforcement; rate limits bound arrivals, concurrency limits bound in-flight work, and reactive backpressure requires a supporting pipeline. Select from the resource and consumer policy, not a generic requirement to add Redis or WebFlux.
- Blocking I/O can justify virtual threads on a compatible JDK; CPU saturation needs bounded CPU work and capacity evidence. Virtual threads add neither database nor CPU capacity.
- Verify the executor actually in use. Boot's Tomcat
threads.maxandmin-sparesettings do not control virtual workers when virtual threads are enabled. - Separate TCP connections, HTTP/2 streams, in-flight operations, executor queues, request admission and downstream pools. Do not build a virtual-thread pool to cap concurrency.
- Bound waits and work with a coherent deadline and cancellation policy. Connection, keep-alive, async, acquisition, query and lock timeouts are different controls.
- Keep resource ownership through completion, timeout and disconnect; request thread exit alone does not prove that downstream work stopped.
Do not recommend a pool size, timeout or compression setting as universally optimal. Keep an adequate setup when no measured bottleneck or violated contract supports a change.
Verification, output and stop condition
Use the smallest test that crosses the relevant boundary: unit tests for pure mapping,
MVC slice for conversion/validation/advice, application context for composition, and a real
server for container/network/filter integration. Boot 4 examples must use available test
modules and APIs; @MockBean/@SpyBean were removed, with Framework @MockitoBean and
@MockitoSpyBean available for appropriate bean overrides. Mock identity does not test JWT
validation. Test transactions do not roll back writes made by another server thread.
For executable reference code, load verification and copy the Customer source bundle to an isolated temporary directory. Production code, package structure, pom and runtime configuration retain the reference; the seven test classes add only descriptive @DisplayName annotations. Its six operations, 19 schemas, eight filter variants and conditional error catalog are mapped in the coverage reference. Read the relevant source/test before adapting it. Supporting application/domain and in-memory storage make the HTTP example runnable; they do not replace a target's design. The source has no security chain, durable store or explicit HTTP byte ceiling. Distinguish its published error catalog from enabled runtime capabilities and test UI interaction separately.
Deliver changed behavior and consumer examples with targeted check results for implementation; for diagnosis/review, deliver prioritized evidence, competing explanations, corrections and the next discriminating check. For documentation, include the chosen contract/guide artifacts, affected operation/property inventory, example validation and publication/access evidence. Report UI results only when UI is supplied. Implement in the order contract decision, DTO/controller integration, shared policy integration, documenting tests, then generation and publication verification; reuse the existing build and tests. For extensive work, keep progress and material decisions in the project's established format; use an ADR for a durable architectural choice, not an annotation correction. Separate executed checks, source-supported conclusions and pending runtime claims.
Finish when the requested contract is implemented or findings are substantiated, relevant checks pass, scope is respected and limitations are explicit. If a server, dependency or UI runner is unavailable, complete static work, state exactly which claim remains unverified and give the command or fixture needed to resolve it. Do not fabricate execution evidence.
Composition
If discovery establishes a WebFlux server, confirm the active stack and resolved Boot/Framework versions, then hand off to an available WebFlux specialist with the request contract, ingress limits, codec configuration and observed failure. Expect a reactive-stack decision and relevant project tests. If no specialist is available, use the matching official Boot reactive and Framework WebFlux references with the project's reactive tests; state any remaining evidence gap. Do not adapt Servlet filters, request-body advice or MVC exception hooks to the reactive pipeline by analogy.
For Boot composition/version/property questions use spring-boot, passing resolved versions,
the active configuration and observed condition report; expect a compatible wiring decision.
For authorization/filter policies use spring-security-for-apis, passing routes, credential
transport, origins and actual 401/403 bodies; expect a tested chain and browser policy.
For persistence use spring-boot-jpa, passing the use-case transaction, query shape and HTTP
consistency contract; expect persistence behavior verified at its own boundary.
For public compatibility choices use rpc-and-api-contracts or remote-facade-and-dto;
for capacity budgets use connection-pool-sizing and thread-sizing-and-virtual-threads.
Pass measured workload, replica/resource limits and required outcomes. If a specialist is
unavailable, preserve the relevant guard here, make the unresolved decision explicit and
continue Web work that does not depend on it. These are optional handoffs, not prerequisites
for every controller.