Use mkdocs-material for documentation

.gitignore

@@ -1,4 +1,134 @@
-.idea
-.gradle
+# Jetbrains
+.idea/
+
+### Kotlin
 .kotlin
-build
+*.class
+*.log
+*.jar
+
+# Dokka
+docs/dokka/
+
+### Visual Studio Code
+.vscode/
+
+# Local History for Visual Studio Code
+.history/
+
+### Linux
+*~
+
+# temporary files which can be created if a process still has a handle open of a deleted file
+.fuse_hidden*
+
+# KDE directory preferences
+.directory
+
+# Linux trash folder which might appear on any partition or disk
+.Trash-*
+
+# .nfs files are created when an open file is removed but is still being accessed
+.nfs*
+
+### Windows
+# Windows thumbnail cache files
+Thumbs.db
+Thumbs.db:encryptable
+ehthumbs.db
+ehthumbs_vista.db
+
+# Dump file
+*.stackdump
+
+# Folder config file
+[Dd]esktop.ini
+
+# Recycle Bin used on file shares
+$RECYCLE.BIN/
+
+# Windows Installer files
+*.cab
+*.msi
+*.msix
+*.msm
+*.msp
+
+# Windows shortcuts
+*.lnk
+
+### Gradle
+.gradle/
+build/
+
+# Ignore Gradle GUI config
+gradle-app.setting
+
+# Avoid ignoring Gradle wrapper jar file (.jar files are usually ignored)
+!gradle-wrapper.jar
+
+# Avoid ignore Gradle wrappper properties
+!gradle-wrapper.properties
+
+# Cache of project
+.gradletasknamecache
+
+# Eclipse Gradle plugin generated files
+# Eclipse Core
+.project
+# JDT-specific (Eclipse Java Development Tools)
+.classpath
+
+### macOS
+# General
+.DS_Store
+.AppleDouble
+.LSOverride
+
+# Icon must end with two \r
+Icon
+
+# Thumbnails
+._*
+
+# Files that might appear in the root of a volume
+.DocumentRevisions-V100
+.fseventsd
+.Spotlight-V100
+.TemporaryItems
+.Trashes
+.VolumeIcon.icns
+.com.apple.timemachine.donotpresent
+
+# Directories potentially created on remote AFP share
+.AppleDB
+.AppleDesktop
+Network Trash Folder
+Temporary Items
+.apdisk
+
+
+### Python
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# pyenv
+.python-version
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# mkdocs documentation
+/site

build.gradle.kts

@@ -5,8 +5,25 @@ plugins {
     id("io.gitlab.arturbosch.detekt") version "1.23.0" apply false
     id("com.vanniktech.maven.publish") version "0.28.0" apply false
     id("com.github.ben-manes.versions") version "0.51.0" apply false
+    id("ru.vyarus.mkdocs") version "4.0.1"
 }
 
 repositories {
     mavenCentral()
 }
+
+mkdocs {
+    sourcesDir = "."
+    buildDir = "./build/mkdocs"
+    updateSiteUrl = true
+    publish {
+        version = "5.0"
+        rootRedirect = true
+        rootRedirectTo = "latest"
+        setVersionAliases("latest")
+        generateVersionsFile = true
+    }
+    python {
+        minPythonVersion = "3.12"
+    }
+}

docs/changelog.md

@@ -0,0 +1 @@
+# Changelog

docs/examples/authentication.md

@@ -0,0 +1,6 @@
+# Authentication
+
+
+```kotlin title="Authentication.kt" linenums="1"
+---8<--- "Authentication.kt"
+```

docs/examples/basics.md

@@ -0,0 +1,118 @@
+[//]: # (# Basics)
+
+[//]: # ()
+[//]: # (This example shows a basic usage of the plugin)
+
+[//]: # ()
+[//]: # (## Complete Example)
+
+[//]: # (```kotlin title="Basics.kt" linenums="1")
+
+[//]: # (--8<-- "Basics.kt")
+
+[//]: # (```)
+
+[//]: # ()
+[//]: # (## Breaking it down)
+
+[//]: # (### Install and configure the plugin)
+
+[//]: # ()
+[//]: # (```kotlin title="Basics.kt")
+
+[//]: # (--8<-- "Basics.kt:24:44")
+
+[//]: # (```)
+
+[//]: # ()
+[//]: # (### Configure routes)
+
+[//]: # ()
+[//]: # (#### Spec routes)
+
+[//]: # ()
+[//]: # (=== "OpenAPI")
+
+[//]: # ()
+[//]: # (    Configure the OpenAPI spec file to be served from `/api.json`)
+
+[//]: # (    )
+[//]: # (    ```kotlin)
+
+[//]: # (    --8<-- "Basics.kt:50:52")
+
+[//]: # (    ```)
+
+[//]: # ()
+[//]: # (=== "Swagger UI")
+
+[//]: # ()
+[//]: # (    Configure Swagger UI to be served from `/swagger` with the OpenAPI spec file at `/api.json`)
+
+[//]: # ()
+[//]: # (    ```kotlin)
+
+[//]: # (    --8<-- "Basics.kt:55:57")
+
+[//]: # (    ```)
+
+[//]: # ()
+[//]: # (=== "ReDoc")
+
+[//]: # ()
+[//]: # (    Configure Swagger UI to be served from `/redoc` with the OpenAPI spec file at `/api.json`)
+
+[//]: # ()
+[//]: # (    ```kotlin)
+
+[//]: # (    --8<-- "Basics.kt:55:57")
+
+[//]: # (    ```)
+
+[//]: # ()
+[//]: # (!!! note)
+
+[//]: # ()
+[//]: # (    The spec routes will not be included in the final OpenAPI spec file)
+
+[//]: # ()
+[//]: # ()
+[//]: # (#### Document a route)
+
+[//]: # ()
+[//]: # (We add information about the route itself)
+
+[//]: # ()
+[//]: # (```kotlin title="Basics.kt" hl_lines="3")
+
+[//]: # (--8<-- "Basics.kt:65:86")
+
+[//]: # (```)
+
+[//]: # ()
+[//]: # (We add information about the request)
+
+[//]: # ()
+[//]: # (```kotlin title="Basics.kt" hl_lines="5-10")
+
+[//]: # (--8<-- "Basics.kt:65:86")
+
+[//]: # (```)
+
+[//]: # ()
+[//]: # (And finally, the response)
+
+[//]: # ()
+[//]: # (```kotlin title="Basics.kt" hl_lines="12-15")
+
+[//]: # (--8<-- "Basics.kt:65:86")
+
+[//]: # (```)
+
+# Basic
+
+This example shows a basic usage of the plugin
+
+```kotlin title="Basics.kt" linenums="1"
+--8<---- "Basics.kt"
+```

docs/examples/complete-configuration.md

@@ -0,0 +1,7 @@
+# Complete Configuration
+
+This example showcases a **nearly** complete - and mostly nonsensical - plugin configuration
+
+```kotlin title="CompleteConfig.kt" linenums="1"
+--8<-- "CompleteConfig.kt"
+```

docs/examples/customized-schema-generator.md

@@ -0,0 +1,5 @@
+# Customized Schema Generator
+
+```kotlin linenums="1"
+---8<--- "CustomizedSchemaGenerator.kt"
+```

docs/examples/external-openapi-spec.md

@@ -0,0 +1,5 @@
+# External OpenAPI Spec
+
+```kotlin linenums="1"
+---8<--- "ExternalOpenApiSpec.kt"
+```

docs/examples/file-upload.md

@@ -0,0 +1,5 @@
+# File Upload
+
+```kotlin linenums="1"
+---8<--- "FileUpload.kt"
+```

docs/examples/kotlinx-serialization.md

@@ -0,0 +1,5 @@
+# Kotlinx Serialization
+
+```kotlin linenums="1"
+---8<--- "KotlinxSerialization.kt"
+```

docs/examples/minimal.md

@@ -0,0 +1,7 @@
+# Minimal
+
+This example showcases using the plugin with most of the default configuration
+
+```kotlin title="Minimal.kt" linenums="1"
+--8<-- "Minimal.kt"
+```

docs/examples/multiple-specs.md

@@ -0,0 +1,5 @@
+# Multiple Specs
+
+```kotlin linenums="1"
+---8<--- "MultipleSpecs.kt"
+```

docs/examples/openapi-examples.md

@@ -0,0 +1,5 @@
+# OpenAPI Examples
+
+```kotlin linenums="1"
+---8<--- "Examples.kt"
+```

docs/examples/petstore.md

@@ -0,0 +1,5 @@
+# Petstore
+
+```kotlin linenums="1"
+---8<--- "Petstore.kt"
+```

docs/examples/request-response.md

@@ -0,0 +1,5 @@
+# Requests and Responses
+
+```kotlin linenums="1"
+---8<--- "RequestResponse.kt"
+```

docs/examples/schemas.md

@@ -0,0 +1,5 @@
+# Schemas
+
+```kotlin linenums="1"
+---8<--- "Schemas.kt"
+```

docs/index.md

@@ -0,0 +1,21 @@
+# Ktor Swagger UI
+
+[![Maven Central](https://maven-badges.herokuapp.com/maven-central/io.github.smiley4/ktor-swagger-ui/badge.svg)](https://search.maven.org/artifact/io.github.smiley4/ktor-swagger-ui)
+[![Checks Passing](https://github.com/SMILEY4/ktor-swagger-ui/actions/workflows/checks.yml/badge.svg?branch=develop)](https://github.com/SMILEY4/ktor-swagger-ui/actions/workflows/checks.yml)
+
+This library provides a [Ktor](https://ktor.io/) plugin to document routes, generate an OpenAPI specification and serve [Swagger UI](https://swagger.io/tools/swagger-ui/) and [ReDoc](https://github.com/Redocly/redoc).
+
+It is meant to be  minimally invasive i.e. it can be plugged into existing application without requiring immediate changes to the code.
+Routes can then be gradually enhanced with documentation.
+
+
+## Features
+
+- Minimally invasive (no immediate change to existing code required)
+- Provides OpenAPI spec, Swagger UI and ReDoc with minimal configuration
+- Supports most of the [OpenAPI 3.1.0 Specification](https://swagger.io/specification/)
+- Automatic [json-schema generation](https://github.com/SMILEY4/schema-kenerator) from arbitrary types/classes for bodies and parameters
+    - Supports generics, inheritance, collections, etc.
+    - (Optional) support for Jackson-annotations and swagger schema annotations
+    - Use with reflection or kotlinx-serialization
+    - Customizable schema generation