jellyfin-sdk-kotlin/openapi-generator

OpenAPI Code Generator

This module is a tool to generate parts of the jellyfin-api and jellyfin-model modules. It uses the OpenAPI specification generated by the server (since 10.7) and transforms it into a custom structure that will be converted into Kotlin code. It will only generate the models and API methods. The API methods always use an instance of KtorClient which implements the actual HTTP calls. Changes to the http client can thus be made without updating the generator.

The generator uses a special hook system to change the generated code to better suite the Kotlin language. For example, the "ImageBlurHashes" property in BaseItemDto can be simplified by using a Map, and therefor a hook is added for it. All these hooks need to be maintained and updated when the OpenAPI specification changes.

Hooks

Hooks are classes that will modify the output of the generator. They should be registered in the HookModule.kt file. The following hooks are available:

• TypeBuilderHook
  A hook that can intercept the TypeBuilder which converts OpenAPI schemas to Kotlin types. It receives the schema and a type path. The path is unique across the whole document and can be used to identified specific properties. This hook is called when generating types for:

  • model properties
  • api operation parameters
  • api operation bodies
  • api operation return types

• OperationUrlHook A hook that can request a url function to be added for an API operation. It receives the model for a complete api service and a single operation. If any hook returns true the generator will add a special function called [operation]Url (like "GetImageUrl") that will return a string containing the request url.

Phases

The conversion happens in multiple phases. The phases in order are:

1. Parse
   Reads the OpenAPI file using swagger-parser, which also validates the document, and returns the OpenAPI specification POJOs

2. Transform
   Converts the POJOs to a custom data model optimized for generating code

3. Generate
   Creates the code for the models and api operations using KotlinPoet

4. Write
   Writes all new code on top of the current code