Source: merged from direct-debit-sandbox-java/learning/06-business-domain-flow.md (the generally-applicable patterns extracted from that project’s mandate/subscription domain) and 08-openapi-and-swagger-docs.md. The custom vanilla-JS docs portal covered in 09-custom-docs-portal-ui.md is frontend work, not Java — it’s summarized here only as context for how a spec gets consumed; the full CSS/JS build (syntax highlighting, retractable sidebar, iframe embedding) is worth reading directly in the original if that’s the part of interest.

RestTemplate — outbound HTTP calls

Spring’s built-in synchronous HTTP client, used for calling out to another service (e.g. firing a webhook after processing completes):

HttpHeaders headers = new HttpHeaders();
headers.setContentType(MediaType.APPLICATION_JSON);
HttpEntity<Object> entity = new HttpEntity<>(payload, headers);
ResponseEntity<String> response = restTemplate.exchange(url, HttpMethod.POST, entity, String.class);

Defined once as a @Bean and injected wherever needed, same as any other Spring-managed dependency (see 01-spring-boot).

A catalogue of common Spring/Java runtime errors

ExceptionUsual cause
NullPointerExceptionCalled a method on a null reference — guard with a null check before use (see 01-fundamentals)
HttpMessageNotReadableExceptionMalformed JSON body, wrong field type, or an enum value that doesn’t match any constant
MethodArgumentNotValidExceptionA @NotBlank/@NotNull field failed validation
NoSuchBeanDefinitionExceptionSpring can’t find a dependency to inject — the target class is missing @Service/@Component/@Bean, or sits outside the scanned package
ConcurrentModificationExceptionA plain HashMap/ArrayList mutated while another thread iterates it — use ConcurrentHashMap (see 02-concurrency)
@Async method runs synchronously with no errorCalled from inside the same class — Spring’s proxy is bypassed (see 01-spring-boot)

The config-resolution / fallback pattern

A common shape: a caller may supply configuration per-request, but should fall back to a default registered once elsewhere (at onboarding, in a cache, in an env var) if they don’t:

private List<ConfigurationItem> resolveEffectiveConfig(List<ConfigurationItem> requested, ProvisionRecord defaults) {
    List<ConfigurationItem> resolved = requested != null ? new ArrayList<>(requested) : new ArrayList<>();
    Set<String> present = resolved.stream().map(ConfigurationItem::getName).collect(Collectors.toSet());
    if (defaults != null && !present.contains("retryAttempts") && defaults.getRetryAttempts() != null) {
        resolved.add(new ConfigurationItem("retryAttempts", defaults.getRetryAttempts().toString()));
    }
    return resolved;
}

Three design choices worth naming explicitly: caller wins (an explicit value always beats a registered default), never overwrite (build the set of already-present keys first, only fill gaps), and null-safe (no config supplied at all still produces a valid, empty starting list). The same shape recurs constantly — cache-then-database, env-var-then-default, per-request-then-account-level-setting.

This is also the mechanism behind the provision pattern: instead of every request carrying repeated per-caller config (a webhook URL, retry limits), a caller registers it once, and every subsequent operation resolves it via a lookup rather than requiring it inline — a normalization decision at the API-design level, not just the schema level (see 01-jdbc-and-data-modeling for the same idea applied to storage).

Enum-based validation and value migration shims

Accepting a field as a plain String accepts anything; typos and invalid values only surface downstream. Typing the field as an enum gets free validation from the JSON deserializer — an unmatched value throws before any handler code runs:

public enum Channel { MTN, TELECEL, AT, AIRTEL, BANK, CARD }
@NotNull private Channel channel;   // was: @NotBlank private String channel

When a value gets renamed but old callers still send the old one (e.g. a rebrand), reject nothing — keep the old value as a valid enum constant and remap it internally before any business logic runs:

public enum Channel { MTN, TELECEL, AT, AIRTEL, BANK, CARD, VODAFONE /* alias for TELECEL */ }
 
if (Channel.VODAFONE == req.getChannel()) {
    req.setChannel(Channel.TELECEL);
    log.info("Channel changed from VODAFONE to TELECEL");   // auditable in production
}

This is a value migration shim — absorbing a caller’s stale vocabulary at the API boundary so every downstream code path only ever has to reason about one canonical value, instead of scattering if (x == OLD || x == NEW) checks throughout the codebase.

Business codes over raw HTTP status

Real payment/banking APIs commonly return HTTP 200 for nearly everything and communicate outcome through a responseCode field in the body — this avoids clients needing two separate error-handling paths (HTTP status and body):

// Before: relies on the client correctly branching on HTTP status
return ResponseEntity.status(HttpStatus.UNAUTHORIZED).body(errorDto);
 
// After: one path — client always parses the body
return ResponseEntity.ok(ApiResponseDto.builder().responseCode("107").responseMessage("...").build());

Not universally correct (it breaks tooling and conventions that assume HTTP status carries meaning) — but it’s a deliberate, common convention in this domain worth recognizing rather than “fixing” when working in an existing fintech API.

OpenAPI and springdoc

OpenAPI (formerly Swagger) is a machine-readable JSON/YAML description of an HTTP API — every endpoint, header, request/response shape, in a format tooling (docs portals, code generators, Postman) can consume without custom integration per API.

springdoc-openapi generates this spec from your code at startup — no YAML hand-written — by scanning @RestController classes, reading each mapped method’s parameters and @RequestBody DTO, and serving the result at /v3/api-docs:

implementation("org.springdoc:springdoc-openapi-starter-webmvc-ui:2.8.9")   // one line — Swagger UI ships at /swagger-ui.html

Annotations shape what the generated spec says without changing runtime behavior:

@Tag(name = "Subscriptions", description = "Create and manage recurring debit subscriptions")   // groups endpoints in the sidebar
@Operation(summary = "Create a subscription", description = "Markdown supported here")           // per-endpoint docs
@Parameter(hidden = true)                                                                         // exclude from the docs form (still injected at runtime)
@Schema(description = "...", example = "0241234001")                                              // per-field docs + pre-filled example
@ApiResponses({ @ApiResponse(responseCode = "401", description = "Missing required headers") })   // document non-200 outcomes

Security schemes let a UI’s “Authorize” button fill in custom auth headers once instead of repeating them on every endpoint’s form:

@SecurityScheme(name = "x-transflowId", type = SecuritySchemeType.APIKEY, in = SecuritySchemeIn.HEADER)

paired with .addSecurityItem(new SecurityRequirement().addList("x-transflowId")) on the spec’s @Bean definition, and @Parameter(hidden = true) on the corresponding @RequestHeader parameters so they don’t also appear as redundant per-endpoint fields.

Consuming the spec — Swagger UI vs. a custom portal

Swagger UI is a JavaScript SPA bundled inside the springdoc jar — it fetches /v3/api-docs and renders a full docs UI from that JSON, knowing nothing about Java or Spring specifically (the same UI documents a Go or Node backend, given the same spec shape). “Try it out” fires a genuine HTTP request from the browser directly at the running server, not a simulation.

A hand-built portal can do exactly the same thing — fetch /v3/api-docs, walk the JSON (resolving $ref pointers into components.schemas manually), and render a custom UI — trading Swagger UI’s zero-maintenance battle-testing for full control over branding and layout. Both read the same spec, so they never drift apart; this is the practical value of generating the spec from code rather than hand-maintaining a YAML file that two consumers could each go stale against independently.

↑ Back to Java Backends — Spring Boot