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:

```sh
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

[swagger-parser]: https://github.com/swagger-api/swagger-parser
[kotlinpoet]: https://github.com/square/kotlinpoet