add more examples to the readmes

README.md

@@ -1,12 +1,117 @@
 # Ktor Plugins
 
-Collection of Ktor plugins, all plugins have the same version that should correspond with the version of Ktor they're
-using.
+![GitHub release (latest SemVer)](https://img.shields.io/github/v/release/LukasForst/ktor-plugins?style=flat-square)
+
+Collection of useful Ktor plugins. All plugins are hosted on Maven central and can be added to your project as easy as:
+
+```kotlin
+implementation("dev.forst", "ktor-<plugin>", "<latest version>")
+```
 
 * [ktor-api-key](ktor-api-key)
-    * Simple authentication provider for Ktor that verifies presence of the API key in the header.
+    * simple authentication provider for Ktor that verifies presence of the API key in the header
 * [ktor-content-security-policy](ktor-content-security-policy)
     * plugin that allows setting [Content-Security-Policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP)
       headers
+* [ktor-openapi-generator](https://github.com/LukasForst/ktor-openapi-generator/)
+    * generates OpenAPI definitions from your server with support for Ktor `>= 2.0.0`
+    * developed in [separate repository](https://github.com/LukasForst/ktor-openapi-generator/) because it is a fork of
+      existing project
 * [ktor-rate-limiting](ktor-rate-limiting)
-    * plugin that enables rate limiting in Ktor
+    * plugin that enables rate limiting in Ktor
+
+## Ktor API Key Authentication Provider
+
+Simple authentication provider for Ktor that verifies presence of the API key in the header. Useful if you want to
+use `X-Api-Key` or similar approaches for request authentication.
+
+```kotlin
+/**
+ * Minimal Ktor application with API Key authentication.
+ */
+fun Application.minimalExample() {
+    // key that will be used to authenticate requests
+    val expectedApiKey = "this-is-expected-key"
+
+    // principal for the app
+    data class AppPrincipal(val key: String) : Principal
+    // now we install authentication feature
+    install(Authentication) {
+        // and then api key provider
+        apiKey {
+            // set function that is used to verify request
+            validate { keyFromHeader ->
+                keyFromHeader
+                    .takeIf { it == expectedApiKey }
+                    ?.let { AppPrincipal(it) }
+            }
+        }
+    }
+
+    routing {
+        authenticate {
+            get {
+                val p = call.principal<AppPrincipal>()!!
+                call.respondText("Key: ${p.key}")
+            }
+        }
+    }
+}
+```
+
+## Ktor Content Security Policy
+
+Plugin that allows setting [Content-Security-Policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP) headers.
+
+```kotlin
+/**
+ * Minimal Ktor application using Content Security Policy.
+ */
+fun Application.minimalExample() {
+    install(ContentSecurityPolicy) {
+        skipWhen { call ->
+            call.request.path().startsWith("/some-ignored-route")
+        }
+        policy(
+            "default-src" to "'none'"
+        )
+    }
+}
+```
+
+## Ktor Rate Limiting
+
+A simple library that enables Rate Limiting in Ktor.
+
+```kotlin
+/**
+ * Minimal Ktor application with Rate Limiting enabled.
+ */
+fun Application.minimalExample() {
+    // install feature
+    install(RateLimiting) {
+        registerLimit(
+            // allow 10 requests
+            limit = 10,
+            // each 1 minute
+            window = Duration.ofMinutes(1)
+        ) {
+            // use host as a key to determine who is who
+            call.request.origin.host
+        }
+        // and exclude path which ends with "excluded"
+        excludeRequestWhen {
+            call.request.path().endsWith("excluded")
+        }
+    }
+    // now add some routes
+    routing {
+        get {
+            call.respondText("Hello ${call.request.origin.host}")
+        }
+        get("excluded") {
+            call.respondText("Hello ${call.request.origin.host}")
+        }
+    }
+}
+```

ktor-api-key/README.md

@@ -1,15 +1,16 @@
 # Ktor API Key Authentication Provider
 
+![GitHub release (latest SemVer)](https://img.shields.io/github/v/release/LukasForst/ktor-plugins?style=flat-square)
+
 Simple authentication provider for Ktor that verifies presence of the API key in the header. Useful if you want to
-use `X-Api-Key` or
-similar approaches for request authentication.
+use `X-Api-Key` or similar approaches for request authentication.
 
 ## Installation
 
 Include following in your `build.gradle.kts`:
 
 ```kotlin
-implementation("dev.forst", "ktor-api-key", "1.1.0")
+implementation("dev.forst", "ktor-api-key", "<latest-version>")
 ```
 
 Versions >= `1.1.0` have implementation for Ktor >= `2.0.0`, use `1.0.0` if you need support for older versions of Ktor.

ktor-content-security-policy/README.md

@@ -1,13 +1,15 @@
 # Ktor Content Security Policy Plugin
 
+![GitHub release (latest SemVer)](https://img.shields.io/github/v/release/LukasForst/ktor-plugins?style=flat-square)
+
 Plugin that allows setting [Content-Security-Policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP) headers.
 
 ## Installation
 
 Include following in your `build.gradle.kts`:
 
 ```kotlin
-implementation("dev.forst", "ktor-content-security-policy", "1.0.0")
+implementation("dev.forst", "ktor-content-security-policy", "<latest version>")
 ```
 
 ## Usage

ktor-openapi-generator/README.md

@@ -0,0 +1,3 @@
+# Ktor OpenAPI Generator
+
+Hosted on different repository: https://github.com/LukasForst/ktor-openapi-generator/

ktor-rate-limiting/README.md

@@ -1,13 +1,15 @@
 # Ktor Rate Limiting
 
+![GitHub release (latest SemVer)](https://img.shields.io/github/v/release/LukasForst/ktor-plugins?style=flat-square)
+
 A simple library that enables Rate Limiting in Ktor.
 
 ## Installation
 
 Include following in your `build.gradle.kts`:
 
 ```kotlin
-implementation("dev.forst", "ktor-rate-limiting", "1.3.3")
+implementation("dev.forst", "ktor-rate-limiting", "<latest version>")
 ```
 
 Versions >= `1.2.0` have implementation for Ktor >= `2.0.0`, use `1.1.0` if you need support for older versions of Ktor.