Generate API client from OpenAPI json

[Mossop]

Plex have finally released an official API spec (yay!): https://developer.plex.tv/pms/

While I may spend some time trying to make sure some of the support we have matches the official spec it might be interesting to experiment with using the json specification to build all the schemas with one of the many tools that exist to do that, progenitor for instance. It might require changing the http client though as most of them seem to end up using reqwest or hyper.

What do you think?

[worried-networking]

Long time no see 😅 I’ve just added it to my todo list for the week, actually, and then I saw your message ☺️

Yeah, I think playing around with code generation, and then adding some syntax sugar on top of it sounds like a very promising idea.

Thanks for keeping me on my toes, Dave!

[worried-networking]

$ cargo progenitor -i openapi.json -o plexapi -n plexapi -v 0.1.0
gen fail: UnexpectedFormat("invalid version: 3.1.0")
Error: generation experienced errors

+ they don't directly host the openapi.json file — it's embedded in the page. Plex Inc. can't do anything easy, can they? :\ I sense that it's going to be a fun journey.

[worried-networking]

For others who might stumble on this. I spent a bit of time trying to generate the client, and failed. Here's what I discovered:

• The shared schema is not quite valid: in the /livetv/sessions and /livetv/sessions/{sessionId} endpoints, the get.responses.200.content.schema.examples key should be located under content directly, not within schema. Easily fixable, only a problem for future schema updates.
• The official OpenApi Generator 7.15.0 does not fully support schemas, which means not all models can be generated automatically (e.g. it does not produce Directory, MediaContainerWithMetadata and plenty of other models).
  • Could be fixed in 7.16.0-snapshot, see [BUG] [Rust] Generator produces empty structs for anyOf schemas OpenAPITools/openapi-generator#21894.
  • openapi-model-generator could've been a solution here, but it doesn't seem properly working with nested objects. E.g. Directory.pivot is generated as a simple Option<Vec<serde_json::Value>>.
• progenitor does not support OpenApi v3.1.0.
  • If you try to use openapi-down-convert, progenitor will still fail with the error UnexpectedFormat("unsupported style of query parameter DeepObject").

[Mossop]

Disappointing yet somehow not surprising. At least we have some more docs to go on than we had before.

[worried-networking]

Tiny update: I tried the current master of the OpenAPI-generator, and it still doesn't work properly. It does generate some objects, but naming is off, and it's not enough of them. In the resulting objects, by some reason, metadata is created as items 🤯 I have no idea if it's caused by the spec itself, or by the generator not fully supporting schemas, but still.

Fun discovery this time: in the spec, the metadata object has two fields: rating — a number between 0 and 10, and Rating — an array of tag objects — and it doesn't have any description. I hate it here 🤣

[worried-networking]

And then I thought — maybe it's just an issue in the Rust generator? So I tried Python. And PHP. And Go, Java, Kotlin. Neither of them generated the damned Directory model. Yet, all of them are trying to use it in the generated code 🤣