Play Framework

feat: annotation-driven OpenAPI schema enrichment for controllers (PF-81)

Read Swagger 3 annotations off controller classes and methods, merge them
on top of the inferred Operation that PF-12's OpenApiGenerator produces.
The new OpenApiAnnotationReader is invoked from the per-operation build
path; controllers and methods with no Swagger annotations produce output
identical to PF-12's inference-only spec (verified by the existing
OpenApiGeneratorTest cases plus a dedicated unannotatedRouteUnchanged
regression check).

Annotations honoured:
- @Operation(summary, description, tags, operationId) on the method
- @Parameter(name, description, required, schema) on a method parameter
- @RequestBody(description, content) on the method
- @ApiResponse / @ApiResponses on the method (per-status-code entries)
- @Tag(name) on the controller class

Merge precedence:
- Annotation-supplied scalar values WIN over inferred values (the
  developer is overriding deliberately).
- Tags are UNIONED, not replaced: the class-level @Tag is the controller-
  wide grouping, method-level @Operation(tags=...) adds finer-grained
  tags. Duplicates are removed but order is preserved.
- Per-status-code responses merge into the responses map; codes the
  developer didn't supply keep the inferred entry (typically a 200 from
  the return-type schema), so a single @ApiResponse(responseCode="404")
  produces an operation with both 200 and 404.

@Schema enrichment is currently limited to implementation() and
description() — richer constraint fields (pattern, min/max, examples,
etc.) fall back to method-signature inference and are out of scope for
this initial cut.

No new dependency: swagger-annotations 2.2.39 was already on the
classpath via PF-12.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>