GeezerVison

Draft / prototype. This is step 5 of the plan discussed in #461. It is stacked on #485, so the diff shows only the codegen commit. The intended destination is v11 on beta; see "Next step" below.

What it does

• Descriptor: codegen/requests.yaml maps each request class to a spec operation in one line, e.g. GetAlbumRequest: {operation: get-an-album}.
• Generator: codegen/generate-requests.py reads everything else from spec/openapi.yaml:
  • verb, path and parameters;
  • Java types (market becomes CountryCode, integers become Integer, …);
  • the assertion-only argument checks, such as limit ranges and the maximum number of IDs;
  • Javadoc, converted from the spec's Markdown and passing doclint;
  • deprecation, and how the response is parsed (single object, array or page, plus the wrapper field when the response nests it).
• Committed output: the generated classes are checked in, so the Maven build needs no Python. A new CI step, generate-requests.py --check, fails if a listed class no longer matches what the generator produces.
• Survey: codegen/survey.py generates every hand-written data request and compares its public setters and return type with the existing class.

Result

All 8 albums requests are now generated:

• Public API unchanged: japicmp against 10.1.0 finds no incompatible change.
• All 420 tests pass; Javadoc, the examples build and check-docs.py pass.
• The Javadoc text now follows Spotify's wording, and the argument checks are consistent across classes.
• It surfaced one disagreement: the spec caps ids for saving or removing albums at 20, while the hand-written classes asserted 50.

Survey across all requests, with nothing configured beyond the operation:

The gaps fall into a few groups:

• Spec schema names that don't follow the model-class naming convention (e.g. PrivateUserObject → User).
• Request bodies, which affect about 10 requests.
• Response shapes not handled yet: snapshot IDs, cursor paging, and search (one spec operation, nine classes here).
• Parameters the library types as enums.
• Return types where the library deliberately differs from the spec.
• A few setters the hand-written classes omit.

Next step (proposal)

For v11 on beta, I'd rather not keep the compatibility workarounds this prototype carries. Instead, generate a clean, uniform shape from the spec and let the generated API be the reference, recording any renames in MIGRATION.md. This PR stays as the evaluation of the approach.

🤖 Generated with Claude Code

https://claude.ai/code/session_01KSXwvJcGsHkEQQs7VNmYpR