refine, link and fix documentation

Author: SMILEY4

docs/assets/stylesheets/extra.css

@@ -16,4 +16,16 @@ details code {
         border-radius: .2rem !important;
         padding: 0 .3rem .3rem .3rem !important;
     }
+}
+
+.md-typeset h2 {
+    margin: 2.5em 0 .64em;
+}
+
+.md-typeset h2 {
+    margin: 2.6em 0 .64em;
+}
+
+.md-typeset h3 {
+  margin-top: 1.2em;
 }

docs/index.md

@@ -21,7 +21,7 @@ Designed to be non-invasive, they integrate seamlessly with applications without
 
     Add documentation to Ktor routes and automatically generate [OpenAPI](https://www.openapis.org/) specifications.
 
-    [:octicons-arrow-right-24: Get Started](openapi/index.md)
+    [:octicons-arrow-right-24: Get Started](./openapi/getting_started.md)
 
 
 -   :simple-swagger:{ .lg .middle } __Swagger UI__

docs/openapi/advanced_topics/documenting_sse_routes.md

@@ -1,12 +1,15 @@
 # Documenting SSE Routes
 
-Server-Sent Events (SSE) routes can be documented for discoverability in the OpenAPI specification. While SSE functionality works normally in Ktor, documentation is achieved by wrapping SSE routes in a documented parent route.
+Server-Sent Events (SSE) routes can be documented for discoverability in the OpenAPI specification.
+While SSE functionality works normally in Ktor, documentation is achieved by wrapping SSE routes in a documented parent route.
 
-??? warning "Limited OpenAPI Support"
+!!! warning "Limited OpenAPI Support"
 
-**Important:** OpenAPI has limited support for Server-Sent Events. The specification does not officially define SSE endpoints, so not all documentation features work as expected or may not render correctly in documentation UIs.
-
-SSE documentation is primarily for discoverability and basic information. Advanced SSE features (event types, reconnection behavior, stream format) are not well-represented in OpenAPI.
+    OpenAPI has limited support for Server-Sent Events. The specification does not officially define SSE endpoints,
+    so not all documentation features work as expected or may not render correctly in documentation UIs.
+    
+    SSE documentation is primarily for discoverability and basic information. Advanced SSE features (event types, reconnection behavior,
+    stream format) are not well-represented in OpenAPI.
 
 
 ## Describing SSE-Routes
@@ -21,10 +24,13 @@ route({
     tags = listOf("events", "sse")
 }) {
     sse("/events") {
-        // SSE implementation
         send(ServerSentEvent(data = "Hello"))
     }
 }
 ```
 
-All standard route documentation options are (theoretically) available. See [Basic Route Documentation]() for complete documentation options.
+??? info "More Information"
+
+    All standard route documentation options are available (in theory). For more information, see:
+
+    [:octicons-arrow-right-24: Basic Route Documentation](./../documenting_routes/basic_route_documentation.md)

docs/openapi/advanced_topics/documenting_webhooks.md

@@ -1,12 +1,13 @@
 # Documenting Webhooks
 
-Webhooks are HTTP callbacks that your API sends to external systems. While webhooks are not part of your server's request handling, they can be documented in the OpenAPI specification to help API consumers understand what data your API will send to their endpoints.
+Webhooks are HTTP callbacks that your API sends to external systems. While webhooks are not part of your server's request handling,
+they can be documented in the OpenAPI specification to help API consumers understand what data your API will send to their endpoints.
 
-??? warning "Documentation Only"
+!!! warning "Documentation Only"
 
-**Important:** Webhook documentation is purely informational. It does not create callable Ktor routes and has no impact on your application's routing or request handling.
-
-Webhooks appear only in the generated OpenAPI specification under the `webhooks` section. They document HTTP requests your API makes to external systems, not requests it receives.
+    Webhook documentation is purely informational. It does not create callable Ktor routes and has no impact on your application's routing or request handling.
+    
+    Webhooks appear only in the generated OpenAPI specification under the `webhooks` section. They document HTTP requests your API makes to external systems, not requests it receives.
 
 ## Describing Webhooks
 
@@ -33,4 +34,8 @@ Parameters:
 - httpMethod: HTTP method for the webhook (typically HttpMethod.Post)
 - eventName: Unique identifier for the webhook event (e.g., "newOrder", "userCreated")
 
-All standard route documentation options are available. See [Basic Route Documentation]() for complete documentation options.
+??? info "More Information"
+
+    All standard route documentation options are available. For more information, see:
+
+    [:octicons-arrow-right-24: Basic Route Documentation](./../documenting_routes/basic_route_documentation.md)

docs/openapi/advanced_topics/multiple_openapi_specifications.md

@@ -1,8 +1,13 @@
 # Multiple API Specifications
 
-The OpenAPI plugin supports generating multiple independent specifications from a single application. This enables API versioning, separation of internal and external APIs, or organizing endpoints by product or team.
+The OpenAPI plugin supports generating multiple independent specifications from a single application.
+This enables API versioning, separation of internal and external APIs, or organizing endpoints by product or team.
+
+Each specification has a unique identifier, its own configuration, and contains only the routes assigned to it.
+Specifications are generated and served independently.
+
+
 
-Each specification has a unique identifier, its own configuration, and contains only the routes assigned to it. Specifications are generated and served independently.
 
 ## Configuring Specifications
 
@@ -12,33 +17,36 @@ All configuration options available in the base plugin config are available for
 
 ```kotlin
 install(OpenApi) {
-    // Base configuration for all specifications
-    info {
+    info { // (1)!
         title = "My API"
     }
-    
-    // Define specification "v1"
-    spec("v1") {
+    spec("v1") { // (2)!
         info {
             version = "1.0.0"
         }
     }
-    
-    // Define specification "v2"
-    spec("v2") {
+    spec("v2") { // (3)!
         info {
             version = "2.0.0"
         }
     }
 }
 ```
 
+1. Base configuration for all specifications
+2. Define and configure specification with identifier "v1"
+3. Define and configure specification with identifier "v2"
+
 Each specification is identified by a unique string (e.g., "v1", "v2", "internal").
 
+
+
+
 ## Assigning Routes to Specifications
 
 Routes must be assigned to specifications to appear in them. Assignment can be done explicitly in route documentation or automatically via an assigner function.
 
+
 ### Assignment at Route Documentation
 
 The `specName` property assigns a route to a specific specification:
@@ -54,16 +62,19 @@ Routes can be easily assigned in groups by adding the `specName` at a parent rou
 
 ```kotlin
 route("v1", {
-    specName = "v1" // All child routes assigned to v1
+    specName = "v1" // (1)!
 }) {
     get("users") { }
     get("products") { }
     get("orders") { }
 }
 ```
 
+1.  All child routes are assigned to "v1".
+
 All routes within this block are automatically assigned to the "v1" specification through inheritance.
 
+
 ### Assignment via Assigner Function
 
 Routes can be automatically assigned based on their properties using an assigner function:
@@ -88,34 +99,41 @@ The function receives:
 
 The function returns the specification identifier to assign the route to.
 
+
 ### Unassigned Routes
 
-Routes without an assignment are assigned to the default specification with the identifier `OpenApiPluginConfig.DEFAULT_SPEC_ID`. The default specification only exists if any routes are assigned to it.
+Routes without an assignment are assigned to the default specification with the identifier `OpenApiPluginConfig.DEFAULT_SPEC_ID`.
+The default specification only exists if any routes are assigned to it.
+
+
+
 
 ## Serving Multiple Specifications
 
 Each specification is served independently via HTTP routes.
 
 ```kotlin
 routing {
-    // v1 specification
-    route("v1/api.json") {
+    route("v1/api.json") { // (1)!
         openApi("v1")
     }
-    
-    // v2 specification
-    route("v2/api.json") {
+    route("v2/api.json") { // (2)!
         openApi("v2")
     }
-    
-    // Internal specification
-    route("internal/api.json") {
+    route("internal/api.json") { // (3)!
         openApi("internal")
     }
 }
 ```
 
-More information on how to handle multiple specifications in UIs:
+1. Expose v1 specification.
+2. Expose v2 specification.
+3. Expose internal specification.
+
+??? info "Multiple Specifications with Swagger UI and Redoc"
+
+    More information on how to handle multiple specifications with documentation UIs:
+
+    [:octicons-arrow-right-24: Swagger UI](./../../swaggerui/getting_started.md)
 
-- with [Swagger UI]()
-- with [ReDoc]()
+    [:octicons-arrow-right-24: ReDoc](./../../redoc/getting_started.md)

docs/openapi/advanced_topics/typesafe_routing_support.md

@@ -1,11 +1,15 @@
 # Type-Safe Routing Support
 
-The OpenAPI plugin supports Ktor's type-safe routing via the Resources plugin. Resource classes can be used to define routes, and the plugin can automatically extract parameter information from resource class properties.
+The OpenAPI plugin supports Ktor's type-safe routing via the Resources plugin. Resource classes can be used to define routes and the plugin
+can automatically extract parameter information from resource class properties.
+
+
 
 ## Setup
 
 Type-safe routing support requires additional configuration:
 
+
 ### Installed Resources Plugin
 
 The Ktor Resources plugin must be installed separately:
@@ -21,6 +25,7 @@ install(Resources)
 install(OpenApi)
 ```
 
+
 ### Configure Schema Generator
 
 Type-safe routing requires the kotlinx.serialization schema generator:
@@ -33,6 +38,7 @@ install(OpenApi) {
 }
 ```
 
+
 ### Enable Auto-Documentation (Optional)
 
 The `autoDocumentResourcesRoutes` option automatically extracts parameter information from resource classes:
@@ -51,6 +57,8 @@ When enabled, the plugin automatically documents:
 
 This reduces the need for manual parameter documentation in resource routes.
 
+
+
 ## Documenting Resource Routes
 
 ### Import Documented Resource Functions
@@ -62,8 +70,10 @@ import io.github.smiley4.ktoropenapi.resources.get
 import io.github.smiley4.ktoropenapi.resources.post
 import io.github.smiley4.ktoropenapi.resources.put
 import io.github.smiley4.ktoropenapi.resources.delete
+// ...
 ```
 
+
 ### Document Resource Routes
 
 The documentation block works the same as with standard routes:
@@ -79,11 +89,9 @@ class Users
 @Resource("{id}")
 class User(val parent: Users, val id: String)
 
-
 get<User>({
     description = "Retrieve a user by ID"
     tags = listOf("users")
-    
     response {
         code(HttpStatusCode.OK) {
             description = "User found"
@@ -94,7 +102,6 @@ get<User>({
         }
     }
 }) {
-    val user = call.parameters["id"]
-    // Handler implementation
+    // handler implementation
 }
 ```