jellyfin-sdk-kotlin/openapi-generator/README.md

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 thus a hook is added for it. All hooks need to be maintained and updated when the OpenAPI specification changes.

Running

The following Gradle tasks can be used to run the generator:

• generateSources
  Reads the openapi.json files and generates Kotlin source code.
• verifySources
  Reads the openapi.json files and verifies existing files.
• downloadApiSpecStable & downloadApiSpecUnstable
  Downloads the openapi.json file from repo.jellyfin.org.
• updateApiSpecStable & updateApiSpecUnstable
  Runs the download task followed by the generateSources task.

Updating the repository

When the repository needs to be updated for a new OpenAPI file the following shell commands are used:

gradlew openapi-generator:updateApiSpecStable
git add .
git commit -m "Update generated sources"
git push

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.

• OperationRequestModelHook
  A hook that can request a request model function to be added for an API operation. Compared to the default function it used a data class to contain all parameters.

• ServiceNameHook
  A hook that can modify the name(s) of an operation. It can add, rename and delete the services for an operation. When all services are removed the operation will never be generated. Can be used to fix spelling, moving operations to different services or adding operations to additional services.

• DefaultValueHook
  A hook that allows changing the default value of parameters in operations. The hook returns an instance of CustomDefaultValue that contains the code builder. The generator will use the default value from the JSON schema if all hooks return null.

• DescriptionHook
  A hook that allows customization of generated descriptions for operations, parameters, models and properties. The hook returns the new description or null if the description must be removed.

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