-
Notifications
You must be signed in to change notification settings - Fork 27
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
chore: rollback docs due to sonatype disaster (#581)
- Loading branch information
Showing
6 changed files
with
138 additions
and
129 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,125 +1,106 @@ | ||
| Kompendium enables users to enrich their payloads with additional metadata | ||
| such as field description, deprecation, and more. | ||
| 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 `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. | ||
| ```kotlin | ||
| data class SimpleData(val a: String, val b: Int? = null) | ||
|
|
||
| A simple enrichment example looks like the following: | ||
| 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 | ||
| } | ||
| } | ||
|
|
||
| ```kotlin | ||
| post = PostInfo.builder { | ||
| summary(TestModules.defaultPathSummary) | ||
| description(TestModules.defaultPathDescription) | ||
| request { | ||
| requestType( | ||
| enrichment = ObjectEnrichment("simple") { | ||
| TestSimpleRequest::a { | ||
| StringEnrichment(id = "simple-enrichment") { | ||
| description = "A simple description" | ||
| } | ||
| // 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 { | ||
| NumberEnrichment(id = "blah-blah-blah") { | ||
| deprecated = true | ||
| } | ||
| response { | ||
| responseCode(HttpStatusCode.Created) | ||
| 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. | ||
|
|
||
| ## Scalar Enrichment | ||
| {% 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. | ||
|
|
||
| Currently, Kompendium supports enrichment of the following scalar types: | ||
| 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 %} | ||
|
|
||
| - Boolean | ||
| - String | ||
| - Number | ||
| ### Nested Enrichments | ||
|
|
||
| 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. | ||
| 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. | ||
|
|
||
| ## 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 | ||
| ```kotlin | ||
| data class ParentData(val a: String, val b: ChildData) | ||
| data class ChildData(val c: String, val d: Int? = null) | ||
|
|
||
| Collection enrichment is used to enrich a collection type, and the elements of that collection. | ||
| 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" | ||
| } | ||
| } | ||
|
|
||
| ```kotlin | ||
| post = PostInfo.builder { | ||
| summary(TestModules.defaultPathSummary) | ||
| description(TestModules.defaultPathDescription) | ||
| request { | ||
| requestType( | ||
| enrichment = ObjectEnrichment("simple") { | ||
| 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") | ||
| val parentEnrichment = TypeEnrichment<ParentData>(id = "parent-enrichment") { | ||
| ParentData::a { | ||
| description = "This will update the field description" | ||
| } | ||
| response { | ||
| responseCode(HttpStatusCode.Created) | ||
| responseType<TestCreatedResponse>() | ||
| description(TestModules.defaultResponseDescription) | ||
| 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 | ||
| get = GetInfo.builder { | ||
| summary(TestModules.defaultPathSummary) | ||
| description(TestModules.defaultPathDescription) | ||
| response { | ||
| responseType<Map<String, TestSimpleRequest>>( | ||
| enrichment = MapEnrichment("blah") { | ||
| description = "A nested description" | ||
| valueEnrichment = ObjectEnrichment("nested") { | ||
| TestSimpleRequest::a { | ||
| StringEnrichment("blah-blah-blah") { | ||
| description = "A simple description" | ||
| } | ||
| } | ||
| TestSimpleRequest::b { | ||
| NumberEnrichment("blah-blah-blah") { | ||
| deprecated = true | ||
| } | ||
| } | ||
| } | ||
| } | ||
| ) | ||
| description("A good response") | ||
| responseCode(HttpStatusCode.Created) | ||
| } | ||
| } | ||
| ``` | ||
| - description -> Provides a reader friendly description of the field in the object | ||
| - deprecated -> Indicates that the field is deprecated and should not be used | ||
|
|
||
| ### String | ||
|
|
||
| - minLength -> The minimum length of the string | ||
| - maxLength -> The maximum length of the string | ||
| - pattern -> A regex pattern that the string must match | ||
| - contentEncoding -> The encoding of the string | ||
| - contentMediaType -> The media type of the string | ||
|
|
||
| ### Numbers | ||
|
|
||
| - minimum -> The minimum value of the number | ||
| - maximum -> The maximum value of the number | ||
| - exclusiveMinimum -> Indicates that the minimum value is exclusive | ||
| - 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 | ||
| - maxItems -> The maximum number of items in the array | ||
| - uniqueItems -> Indicates that the array must contain unique items |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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 |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters