Fix Finding OpenAPI response schema

[omobolajiadeyan]

Description

Define the nested fields returned by the v1 finding endpoints so the generated OpenAPI contract exposes typed component, vulnerability, analysis, and attribution models instead of free-form objects.

The endpoint runtime response is unchanged. The new FindingResponse value object is used only as the Swagger response schema, including the existing millisecond epoch representation for finding timestamps.

A database-free regression test verifies both the /v1/finding/project/{uuid} response reference and the generated nested schema properties.

Addressed Issue

Fixes #2590.

Additional Details

Validation performed with JDK 25 and Maven 3.9.11:

• mvn test -Dmaven.build.cache.enabled=false -Dcheckstyle.skip -Dcyclonedx.skip -pl apiserver -am -Dtest=FindingOpenApiSchemaTest -Dsurefire.failIfNoSpecifiedTests=false
• mvn validate -Dmaven.build.cache.enabled=false
• git diff --check

The focused test passed across the 66-module reactor, and project-wide Java lint completed with zero Checkstyle violations.

Checklist

• I have read and understand the contributing guidelines
• This PR fixes a defect, and I have provided tests to verify that the fix is effective
• This PR implements an enhancement, and I have provided tests to verify that it works as intended
• This PR introduces changes to the database model, and I have updated the migration changelog accordingly
• This PR introduces new or alters existing behavior, and I have updated the documentation accordingly
• This PR is a substantial change (per the ADR criteria), and I have added an ADR under docs/adr/

[owasp-dt-bot]

✅ Snyk checks have passed. No issues have been found so far.

Status	Scan Engine	Critical	High	Medium	Low	Total (0)
✅	Open Source Security	0	0	0	0	0 issues

💻 Catch issues earlier using the plugins for VS Code, JetBrains IDEs, Visual Studio, and Eclipse.

[codacy-production]

Up to standards ✅

🟢 Issues 0 issues

Results:
0 new issues

View in Codacy

🟢 Metrics 0 complexity · -2 duplication

Metric	Results
Complexity	0
Duplication	-2

View in Codacy

_{NEW Get contextual insights on your PRs based on Codacy's metrics, along with PR and Jira context, without leaving GitHub. Enable AI reviewer
TIP This summary will be updated as you push new changes.}

[nscuro]

Thanks for the PR.

The new FindingResponse class is only ever used for advertising a schema, and never actually used in code. So there'd now be a risk of it drifting from the actual data shape being returned by the API.

The resource should actually convert Finding objects to FindingResponse, and return that. That way, there'd be a kind of runtime-assurance that the schema advertises the correct response shape.

That would also allow you to remove FindingOpenApiSchemaTest, which provides no additional value once the runtime-assurance is in place.

[omobolajiadeyan]

Thanks for the review. I updated both JSON finding endpoints to convert the internal Finding objects to FindingResponse before returning them, so the advertised schema is now exercised by the runtime response path. The SARIF path continues to use the internal model. I also removed FindingOpenApiSchemaTest as suggested. The 66-module compile reactor and Checkstyle pass locally.

[omobolajiadeyan]

I pushed a follow-up fix for the failing FindingResourceTest assertions. The typed FindingResponse now omits null optional fields to preserve the previous JSON response behavior, and the component response includes latestVersion again when package metadata enrichment adds it.\n\nI could not rerun the Maven test suite locally on this machine because Maven is not installed in the shell environment, but the patch targets the two CI failures directly.

[omobolajiadeyan]

Hi @nscuro, I believe the requested changes are now addressed: the JSON finding endpoints convert internal Finding objects to FindingResponse before returning them, the SARIF path continues to use the internal model, the schema-only test was removed, and the follow-up JSON behavior fixes were pushed. DCO, Codacy, and Snyk are green. Could you re-review when you have a chance? Happy to adjust further if you prefer a different shape.