Example Configuration and Shared Examples - SMILEY4/ktor-openapi-tools GitHub Wiki

Customizing Example Encoding

The encoding of example values can be customized with the encoder config. If no encoder is specified, the example value will be encoded by swagger.

install(SwaggerUI) {
    examples {

        encoder { type, example ->
            // always encoding example as a string
            example.toString()
        }

    }
}

Parameters

• type - information about the type the example is for
• example - the example value to encode

Shared Examples

Global/Shared examples can be defined in the examples section of the plugin config and then referenced by route documentation. Shared examples are placed in the components/examples-section of the final OpenApi-spec.

Defining Shared Examples

install(SwaggerUI) {
    examples {

        example("Shared A") {
            description = "first shared example"
            value = MyExampleClass(
                someValue = "shared a"
            )
        }

        example("Shared B") {
            description = "second shared example"
            value = MyExampleClass(
                someValue = "shared b"
            )
        }

    }
}

Referencing Shared Examples in Routes

body<MyExampleClass> {
    // reference two shared examples specified in the plugin-config
    exampleRef("Example 1", "Shared A")
    exampleRef("Example 2", "Shared B")
}