more documentation

docs/index.md

@@ -3,6 +3,7 @@ hide:
   - title
   - navigation
   - toc
+  - footer
 ---
 
 # Ktor OpenAPI Tools

docs/openapi/example_encoding.md

@@ -1,53 +1,69 @@
 # Example Encoding
 
-## Customizing Example Encoding
-The encoding of example values can be customized with the encoder config.
+Example objects are automatically serialized (as json) and added to the OpenAPI specification.
+The encoding of example values can be customized in the plugin configuration.
 If no encoder is specified, the example value will be encoded by swagger.
 
-```kotlin
-install(OpenApi) {
-    examples {
-        encoder { type, example ->
-            // always encoding example as a string
-            example.toString()
+## Pre-Defined Example Encoders
+
+=== "Swagger"
+    Explicitly use the internal swagger example encoder. 
+
+    ```kotlin
+    install(OpenApi) {
+        examples {
+            encoder = ExampleEncoder.internal()
         }
     }
-}
-```
+    ```
+
+    ??? info "More Information"
+
+        [:octicons-arrow-right-24: API Reference](../dokka/ktor-openapi/ktor-openapi/io.github.smiley4.ktoropenapi.config/-example-encoder/internal.html)
 
-## Shared Examples
+=== "Kotlinx.Serialization"
+    Use [kotlinx.serialization](https://github.com/Kotlin/kotlinx.serialization) to encode example values.
+
+    ```kotlin
+    install(OpenApi) {
+        examples {
+            encoder = ExampleEncoder.kotlinx()
+        }
+    }
+    ```
 
-Global or 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.
+    ??? info "More Information"
 
-### Defining Shared Examples
+        [:octicons-arrow-right-24: API Reference](../dokka/ktor-openapi/ktor-openapi/io.github.smiley4.ktoropenapi.config/-example-encoder/kotlinx.html)
+
+
+## Custom Example Encoder
+
+The example encoder can be completely replaced by an own implementation.
 
 ```kotlin
 install(OpenApi) {
     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"
-            )
+        encoder { type, example -> //(1)!
+            TOOD() //(2)!
         }
     }
 }
 ```
 
-### Referencing Shared Examples in Routes
+1. Input of the example encoding function is a `io.github.smiley4.ktoropenapi.config.TypeDescriptor` with information about the type/schema and the actual value of the example.
+2. Encode/Transform the example value and return the result.
 
-```kotlin
-body<MyExampleClass> {
-    // reference two shared examples specified in the plugin configuration
-    exampleRef("Example 1", "Shared A")
-    exampleRef("Example 2", "Shared B")
-}
-```
+???+ example "Custom "toString()" Example Encoder"
+
+    ```kotlin
+    install(OpenApi) {
+        examples {
+            encoder { type, example ->
+                example.toString() //(1)!
+            }
+        }
+    }
+    ```
+
+    1. Always encode and embed the example value as a raw string.

docs/openapi/getting_started.md

@@ -47,7 +47,7 @@ install(OpenApi) { //(1)!
 1. Install the "OpenAPI" plugin to the application.
 2. Add additional plugin configuration here.
 
-??? info "Further Information"
+??? info "More Information"
 
     [:octicons-arrow-right-24: Plugin Configuration](plugin_configuration.md)
 
@@ -69,7 +69,7 @@ routing {
 1. Create a new route to expose the OpenAPI specification file at `api.json`.
 2. Expose the OpenAPI specification.
 
-??? info "Further Information"
+??? info "More Information"
 
     [:octicons-arrow-right-24: Multiple OpenAPI Specifications](multiple_specs.md)
 
@@ -102,7 +102,7 @@ get("hello", { //(2)!
 5. Specify the response body type. The schema for the type is generated automatically.
 6. Handle requests as usual.
 
-??? info "Further Information"
+??? info "More Information"
 
     [:octicons-arrow-right-24: Documenting Routes](documenting_routes.md)
 

docs/openapi/handling_types_and_schemas.md → docs/openapi/handling_types_schemas_examples.md

@@ -1,11 +1,11 @@
-# Handling Types and Schemas
+# Handling Types, Schemas and Examples
 
 
 ## Local Types and Schemas
 
 Usually, schemas for request and response bodies, headers and parameters are specified directly at the route and then automatically collected during generation of the OpenAPI specification.
 
-There are three main ways of specifying the schema of any object:
+There are three main ways of specifying the schema of any object directly at the route:
 
 === "Type Parameter"
     The type can be specified via a type parameter.</br>The schema is then generated automatically.
@@ -89,6 +89,10 @@ In addition to types and schema specified directly at the routes, global schemas
     2. Define a new global schema with id `string` by passing a `KType` to `schema`. The actual schema for the type is generated automatically.
     3. Define a new global schema with id `integer` by passing a `io.swagger.v3.oas.models.media.Schema` to `schema`.
 
+??? info "More Information"
+
+    [:octicons-arrow-right-24: API Reference](../dokka/ktor-openapi/ktor-openapi/io.github.smiley4.ktoropenapi.config/-schema-config/index.html)
+
 Global schemas can be referenced by any route documentation by their schema id using the `ref`-function
 
 ???+ example "Referencing Global Schemas"
@@ -114,4 +118,112 @@ Global schemas can be referenced by any route documentation by their schema id u
     3. Use the global schema with id `example-1` as the request body schema.
 
 
-## Composite Schemas
+## Composite Schemas
+
+Schemas and types can be combined to created variations without having to create new classes.
+
+### array
+
+Creates a schema of an array containing items of the specified type or schema.
+
+```kotlin
+import io.github.smiley4.ktoropenapi.config.array
+
+body(array<ExampleData>()) //(1)!
+```
+
+1. The schema of the body is an array of `ExampleData`.
+
+### anyOf
+
+Creates a schema that describes any one of the specified types or schemas.
+
+```kotlin
+import io.github.smiley4.ktoropenapi.config.anyOf
+
+body(anyOf( //(1)!
+    typeOf<ExampleData>(),
+    typeOf<OtherData>()
+))
+```
+
+1. The schema of the body is either an `ExampleData` or an `OtherData`.
+
+???+ tip "Nested Composite Schemas"
+
+    The operations `array` and `anyOf` as well as `ref` and `type` can be combined and nested to create more complex variations.
+
+    ```kotlin
+    body(
+        anyOf(
+            array<String>(),
+            anyOf(
+                ref("my-schema"),
+                type<MyExampleData>()
+            ),        
+        )
+    )
+    ```
+
+## Local Examples
+
+
+Usually, examples for request and response bodies, headers, parameters, etc. are specified directly at the route and then automatically collected during generation of the OpenAPI specification.
+Example values can be specified as normal Kotlin/Java objects that get transformed to "json" and added to the OpenAPI specification.
+
+```kotlin
+body<ExampleData> { //(1)!
+    example("First Example") {
+        value = ExampleData()
+        description = "..."
+        summary = "..."
+    }
+    example("Second Example") {
+        //...
+    }
+}
+```
+
+1. A body is used as an example here. It works the same for parameters, headers, etc.
+
+
+## Global Examples
+
+Global or "shared" examples can be defined in the examples section of the plugin configuration and are placed in the components/examples section of the final OpenAPI specification.
+
+???+ example "Defining Global Examples"
+
+    ```kotlin
+    install(OpenApi) {
+        examples {
+            example("first-global") {
+                description = "first global example"
+                value = ExampleData()
+            }
+            example("second-global") {
+                description = "second global example"
+                value = ExampleData()
+            }
+            //...
+        }
+    }
+    ```
+
+??? info "More Information"
+
+    [:octicons-arrow-right-24: API Reference](../dokka/ktor-openapi/ktor-openapi/io.github.smiley4.ktoropenapi.config/-example-config/index.html)
+
+Global examples can then be referenced by any route documentation by their ids.
+
+???+ example "Referencing Global Examples"
+
+    ```kotlin
+    body<ExampleData> { //(2)!
+        exampleRef("Example 1", "first-global") //(2)!
+        exampleRef("Example 2", "second-global")
+        //...
+    }
+    ```
+
+    1. A body is used as an example here. It works the same for parameters, headers, etc.
+    2. Reference the global example with id `first-global` and add it with the name `Example 1`.

docs/openapi/index.md

@@ -5,8 +5,8 @@
 
 ## Features
 
-- Extends existing Ktor dsl
-- No immediate change to existing code required
+- Extends existing Ktor DSL
+- No immediate change to code required
 - Supports [OpenAPI 3.1.0 Specification](https://swagger.io/specification/)
 - Automatically generates json schemas from kotlin types
     - Out-of-the-box support for type parameters, inheritance, collections, etc