chore: rollback docs due to sonatype disaster (#581)

docs/concepts/enrichment.md

@@ -1,125 +1,106 @@
-Kompendium enables users to enrich their payloads with additional metadata
+Kompendium allows users to enrich their data types with additional information. This can be done by defining a
-such as field description, deprecation, and more.
+`TypeEnrichment` object and passing it to the `enrichment` parameter of the relevant `requestType` or `responseType`.
-
-Enrichments, unlike annotations, are fully decoupled from the implementation of the class
-itself. As such, we can not only enable different metadata on the same class in different
-areas of the application, we can also reuse the same metadata in different areas, and even
-support enrichment of types that you do not own, or types that are not easily annotated,
-such as collections and maps.
-
-A simple enrichment example looks like the following:
 
 ```kotlin
-post = PostInfo.builder {
+data class SimpleData(val a: String, val b: Int? = null)
-  summary(TestModules.defaultPathSummary)
+
-  description(TestModules.defaultPathDescription)
+val myEnrichment = TypeEnrichment<SimpleData>(id = "simple-enrichment") {
-  request {
+  SimpleData::a {
-    requestType(
+    description = "This will update the field description"
-      enrichment = ObjectEnrichment("simple") {
+  }
-        TestSimpleRequest::a {
+  SimpleData::b {
-          StringEnrichment(id = "simple-enrichment") {
+    // Will indicate in the UI that the field will be removed soon
-            description = "A simple description"
+    deprecated = true
-          }
+  }
+}
+
+// In your route documentation
+fun Routing.enrichedSimpleRequest() {
+  route("/example") {
+    install(NotarizedRoute()) {
+      parameters = TestModules.defaultParams
+      post = PostInfo.builder {
+        summary(TestModules.defaultPathSummary)
+        description(TestModules.defaultPathDescription)
+        request {
+          requestType<SimpleData>(enrichment = myEnrichment) // Simply attach the enrichment to the request
+          description("A test request")
         }
-        TestSimpleRequest::b {
+        response {
-          NumberEnrichment(id = "blah-blah-blah") {
+          responseCode(HttpStatusCode.Created)
-            deprecated = true
+          responseType<TestCreatedResponse>()
-          }
+          description(TestModules.defaultResponseDescription)
         }
       }
-    )
+    }
-    description("A test request")
-  }
-  response {
-    responseCode(HttpStatusCode.Created)
-    responseType<TestCreatedResponse>()
-    description(TestModules.defaultResponseDescription)
   }
 }
 ```
 
-For more information on the various enrichment types, please see the following sections.
+{% hint style="warning" %}
+An enrichment must provide an `id` field that is unique to the data class that is being enriched. This is because
+under the hood, Kompendium appends this id to the data class identifier in order to support multiple different
+enrichments
+on the same data class.
 
-## Scalar Enrichment
+If you provide duplicate ids, all but the first enrichment will be ignored, as Kompendium will view that as a cache hit,
+and skip analyzing the new enrichment.
+{% endhint %}
 
-Currently, Kompendium supports enrichment of the following scalar types:
+### Nested Enrichments
 
-- Boolean
+Enrichments are portable and composable, meaning that we can take an enrichment for a child data class
-- String
+and apply it inside a parent data class using the `typeEnrichment` property.
-- Number
-
-At the moment, all of these types extend a sealed interface `Enrichment`... as such you cannot provide
-enrichments for custom scalars like dates and times. This is a known limitation, and will be addressed
-in a future release.
-
-## Object Enrichment
-
-Object enrichment is the most common form of enrichment, and is used to enrich a complex type, and
-the fields of a class.
-
-## Collection Enrichment
-
-Collection enrichment is used to enrich a collection type, and the elements of that collection.
 
 ```kotlin
-post = PostInfo.builder {
+data class ParentData(val a: String, val b: ChildData)
-  summary(TestModules.defaultPathSummary)
+data class ChildData(val c: String, val d: Int? = null)
-  description(TestModules.defaultPathDescription)
+
-  request {
+val childEnrichment = TypeEnrichment<ChildData>(id = "child-enrichment") {
-    requestType(
+  ChildData::c {
-      enrichment = ObjectEnrichment("simple") {
+    description = "This will update the field description of field c on child data"
-        ComplexRequest::tables {
-          CollectionEnrichment<NestedComplexItem>("blah-blah") {
-            description = "A nested description"
-            itemEnrichment = ObjectEnrichment("nested") {
-              NestedComplexItem::name {
-                StringEnrichment("beleheh") {
-                  description = "A nested description"
-                }
-              }
-            }
-          }
-        }
-      }
-    )
-    description("A test request")
   }
-  response {
+  ChildData::d {
-    responseCode(HttpStatusCode.Created)
+    description = "This will update the field description of field d on child data"
-    responseType<TestCreatedResponse>()
+  }
-    description(TestModules.defaultResponseDescription)
+}
+
+val parentEnrichment = TypeEnrichment<ParentData>(id = "parent-enrichment") {
+  ParentData::a {
+    description = "This will update the field description"
+  }
+  ParentData::b {
+    description = "This will update the field description of field b on parent data"
+    typeEnrichment = childEnrichment // Will apply the child enrichment to the internals of field b
   }
 }
 ```
 
-## Map Enrichment
+## Available Enrichments
 
-Map enrichment is used to enrich a map type, and the keys and values of that map.
+All enrichments support the following properties:
 
-```kotlin
+- description -> Provides a reader friendly description of the field in the object
-get = GetInfo.builder {
+- deprecated -> Indicates that the field is deprecated and should not be used
-  summary(TestModules.defaultPathSummary)
+
-  description(TestModules.defaultPathDescription)
+### String
-  response {
+
-    responseType<Map<String, TestSimpleRequest>>(
+- minLength -> The minimum length of the string
-      enrichment = MapEnrichment("blah") {
+- maxLength -> The maximum length of the string
-        description = "A nested description"
+- pattern -> A regex pattern that the string must match
-        valueEnrichment = ObjectEnrichment("nested") {
+- contentEncoding -> The encoding of the string
-          TestSimpleRequest::a {
+- contentMediaType -> The media type of the string
-            StringEnrichment("blah-blah-blah") {
+
-              description = "A simple description"
+### Numbers
-            }
+
-          }
+- minimum -> The minimum value of the number
-          TestSimpleRequest::b {
+- maximum -> The maximum value of the number
-            NumberEnrichment("blah-blah-blah") {
+- exclusiveMinimum -> Indicates that the minimum value is exclusive
-              deprecated = true
+- exclusiveMaximum -> Indicates that the maximum value is exclusive
-            }
+- multipleOf -> Indicates that the number must be a multiple of the provided value
-          }
+
-        }
+### Arrays
-      }
+
-    )
+- minItems -> The minimum number of items in the array
-    description("A good response")
+- maxItems -> The maximum number of items in the array
-    responseCode(HttpStatusCode.Created)
+- uniqueItems -> Indicates that the array must contain unique items
-  }
-}
-```

docs/index.md

@@ -9,9 +9,8 @@ you to rip out and replace the amazing code you have already written.
 | 1.X        | 1    | 3.0     |
 | 2.X        | 1    | 3.0     |
 | 3.X        | 2    | 3.1     | 
-| 4.X        | 2    | 3.1     | 
 
-> These docs are focused solely on Kompendium 4, previous versions should be considered deprecated and no longer
+> These docs are focused solely on Kompendium 3, previous versions should be considered deprecated and no longer
 > maintained
 
 # Getting Started
@@ -37,11 +36,9 @@ custom type overrides (typically useful for custom scalars such as dates and tim
 ```kotlin
 private fun Application.mainModule() {
   install(NotarizedApplication()) {
-    spec = {
+    spec = OpenApiSpec(
-        OpenApiSpec(
+      // ...
-        // ...
+    )
-      )
-    }
   }
 }
 ```

docs/playground.md

@@ -1,6 +1,20 @@
 The Playground is a module inside the Kompendium repository that provides out of the box examples for a variety of
 Kompendium features.
 
-You can find all the playground
+At the moment, the following playground applications are
+
+| Example      | Description                                                |
+|--------------|------------------------------------------------------------|
+| Basic        | A minimally viable Kompendium application                  |
+| Auth         | Documenting authenticated routes                           |
+| Custom Types | Documenting custom scalars to be used by Kompendium        |
+| Exceptions   | Documenting exception responses                            |
+| Gson         | Serialization using Gson instead of the default Kotlinx    |
+| Hidden Docs  | Place your generated documentation behind authorization    |
+| Jackson      | Serialization using Jackson instead of the default KotlinX |
+| Locations    | Using the Ktor Locations API to define routes              |
+| Resources    | Using the Ktor Resources API to define routes              |
+
+You can find all of the playground
 examples [here](https://github.com/bkbnio/kompendium/tree/main/playground/src/main/kotlin/io/bkbn/kompendium/playground)
 in the Kompendium repository

docs/plugins/notarized_application.md

@@ -20,22 +20,21 @@ reference [OpenAPI spec](https://spec.openapis.org/oas/v3.1.0) itself.
 For public facing APIs, having the default endpoint exposed at `/openapi.json` is totally fine. However, if you need
 more granular control over the route that exposes the generated schema, you can modify the `openApiJson` config value.
 
-For example, if we want to hide our schema behind a basic auth check with a custom json encoder, we could do the
+For example, if we want to hide our schema behind a basic auth check, we could do the following
-following
 
 ```kotlin
 private fun Application.mainModule() {
   // Install content negotiation, auth, etc...
   install(NotarizedApplication()) {
     // ...
-    specRoute = { spec, routing ->
+    openApiJson = {
-      routing {
+      authenticate("basic") {
-        authenticate("basic") {
+        route("/openapi.json") {
-          route("/openapi.json") {
+          get {
-            get {
+            call.respond(
-              call.response.headers.append("Content-Type", "application/json")
+              HttpStatusCode.OK,
-              call.respondText { CustomJsonEncoder.encodeToString(spec) }
+              this@route.application.attributes[KompendiumAttributes.openApiSpec]
-            }
+            )
           }
         }
       }
@@ -75,14 +74,32 @@ This means that we only need to define our custom type once, and then Kompendium
 application.
 
 > While intended for custom scalars, there is nothing stopping you from leveraging custom types to circumvent type
-> analysis on any class you choose. If you have an alternative method of generating JsonSchema definitions, you could
+> analysis
-> put them all in this map and effectively prevent Kompendium from having to do any reflection
+> on any class you choose. If you have an alternative method of generating JsonSchema definitions, you could put them
+> all
+> in this map and effectively prevent Kompendium from having to do any reflection
 
 ## Schema Configurator
 
-Out of the box, Kompendium supports KotlinX serialization... however, in order to allow for users of other
+The `SchemaConfigurator` is an interface that allows users to bridge the gap between Kompendium serialization and custom
-serialization libraries to use Kompendium, we have provided a `SchemaConfigurator` interface that allows you to
+serialization strategies that the serializer they are using for their API. For example, if you are using KotlinX
-configure how Kompendium will generate schema definitions.
+serialization in order to convert kotlin fields from camel case to snake case, you could leverage
+the `KotlinXSchemaConfigurator` in order to instruct Kompendium on how to serialize values properly.
 
-For an example of the `SchemaConfigurator` in action, please see the `KotlinxSchemaConfigurator`. This will give you
+```kotlin
-a good idea of the additional functionality it can add based on your own serialization needs.
+private fun Application.mainModule() {
+  install(ContentNegotiation) {
+    json(Json {
+      serializersModule = KompendiumSerializersModule.module
+      encodeDefaults = true
+      explicitNulls = false
+    })
+  }
+  install(NotarizedApplication()) {
+    spec = baseSpec
+    // Adds support for @Transient and @SerialName
+    // If you are not using them this is not required.
+    schemaConfigurator = KotlinXSchemaConfigurator()
+  }
+}
+```

docs/plugins/notarized_locations.md

@@ -23,7 +23,7 @@ level plugin, and **must** be install after both the `NotarizedApplication` plug
 private fun Application.mainModule() {
   install(Locations)
   install(NotarizedApplication()) {
-    spec = { baseSpec }
+    spec = baseSpec
   }
   install(NotarizedLocations()) {
     locations = mapOf(

docs/plugins/notarized_resources.md

@@ -30,7 +30,7 @@ application in a single block.
 private fun Application.mainModule() {
   install(Resources)
   install(NotarizedApplication()) {
-    spec = { baseSpec }
+    spec = baseSpec
   }
   install(NotarizedResources()) {
     resources = mapOf(