feat: type enrichment (#408)

docs/plugins/notarized_route.md

@@ -168,7 +168,7 @@ get = GetInfo.builder {
 
 ## Media Types
 
-By default, Kompendium will set the only media type to "application/json".  If you would like to override the media type 
+By default, Kompendium will set the only media type to "application/json". If you would like to override the media type
 for a specific request or response (including errors), you can do so with the `mediaTypes` method
 
 ```kotlin
@@ -204,3 +204,89 @@ route("/user/{id}") {
   }
 }
 ```
+
+## Enrichment
+
+Kompendium allows users to enrich their data types with additional information. This can be done by defining a
+`TypeEnrichment` object and passing it to the `enrich` function on the `NotarizedRoute` builder. Enrichments
+can be added to any request or response.
+
+```kotlin
+data class SimpleData(val a: String, val b: Int? = null)
+
+val myEnrichment = TypeEnrichment<SimpleData>(id = "simple-enrichment") {
+  SimpleData::a {
+    description = "This will update the field description"
+  }
+  SimpleData::b {
+    // Will indicate in the UI that the field will be removed soon
+    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")
+        }
+        response {
+          responseCode(HttpStatusCode.Created)
+          responseType<TestCreatedResponse>()
+          description(TestModules.defaultResponseDescription)
+        }
+      }
+    }
+  }
+}
+```
+
+{% 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.
+
+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 %}
+
+At the moment, the only available enrichments are the following
+
+- description -> Provides a reader friendly description of the field in the object
+- deprecated -> Indicates that the field is deprecated and should not be used
+
+### Nested Enrichments
+
+Enrichments are portable and composable, meaning that we can take an enrichment for a child data class 
+and apply it inside a parent data class using the `typeEnrichment` property.
+
+```kotlin
+data class ParentData(val a: String, val b: ChildData)
+data class ChildData(val c: String, val d: Int? = null)
+
+val childEnrichment = TypeEnrichment<ChildData>(id = "child-enrichment") {
+  ChildData::c {
+    description = "This will update the field description of field c on child data"
+  }
+  ChildData::d {
+    description = "This will update the field description of field d on child data"
+  }
+}
+
+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
+  }
+}
+```