[cryptalith]

What

The first of four stacked drafts for COMMS-5397 (an OpenAPI 3.0.3 description of API v3.0). This one wires the generator; it adds no operation metadata and commits no spec yet.

• Generator. swagger-maven-plugin-jakarta 2.2.55 is configured once in the root pluginManagement and runs at process-classes in orcid-pub-web and orcid-api-web. It writes target/openapi/{public,member}-v3.0.yaml, so nothing generated is committed in this PR.
• org.orcid.api.common.openapi. Two classes, used by the generator only:
  • OrcidObjectMapperProcessor makes the generator name properties the way OrcidJacksonJaxbJsonProvider serialises them, through JAXB annotations. It switches off XML root names, so schema names come from @Schema(name); otherwise record.Works and record.summary.Works overwrite each other as works.
  • OrcidOpenApiFilter:
    • hides the non-API methods (Swagger UI page, status, the test /error);
    • strips the ; qs= quality factor from media types;
    • pins /v{version}/identifiers to /v3.0/identifiers;
    • describes what the JSON provider really writes: every value may be null, and dates are milliseconds since the epoch.
• Base files. openapi/base/{public,member}-v3.0.yaml hold info and servers, and are merged in by the plugin.
• Record-summary schemas. org.orcid.core.model.* get explicit @Schema(name = "RecordSummary…"); their simple names clash with orcid-model's.
• orcid-model.version property. The pinned orcid-model version becomes a property, so a build can use an unreleased one.

Runtime impact

None. The new dependency is provided, and the plugin brings its own swagger, so nothing new reaches a war. It is declared first in orcid-api-common because orcid-model also puts swagger 2.1.1 (same package names) on the compile classpath. Everything else is annotations and build configuration.

How it was checked

• Executed test counts:

  • orcid-api-common: 105 tests, including 9 new ones for the two helpers;
  • orcid-core: 1879;
  • orcid-pub-web: 390;
  • orcid-api-web: 1249.

  All with 0 failures.

• Build against the released orcid-model 4.0.2 succeeds and generates both files. They still show 4.0.2's annotation defects, which COMMS-5397 OpenAPI-ready @Schema annotations for the v3.0 model orcid-model#87 fixes.

• Contract tests. With Dev fix switch lang in oauth #87 installed locally, the generated files are validated against a running stack built from this branch, with the real ORCID-Oauth server and a fresh database. They validate a public and a member record read, strictly, with unknown properties rejected.

What follows

• (b) Member v3 operation annotations, ported from the 2023 Swagger annotations and checked against each delegator.
• (c) Public v3, webhooks and identifiers annotations.
• (d) Once orcid-model 4.0.3 is released: bump it, commit openapi/*.yaml, and add conformance tests, lint and a drift check in test_mvn.yml.