naijun0403/kompendium
1
0
Fork 0
Code Issues 1 Pull Requests Actions Packages Projects Releases Wiki Activity

update readme

Browse Source
This commit is contained in:
Ryan Brink
2021-11-13 09:39:35 -05:00
parent d9d0f129b5
commit d2165d23bf
1 changed files with 51 additions and 43 deletions
Download Patch File Download Diff File Expand all files Collapse all files

94
README.md
View File

@ -6,13 +6,15 @@
## What is Kompendium ## What is Kompendium
Kompendium is intended to be a minimally invasive OpenApi Specification generator for [Ktor](https://ktor.io). ### ⚠️ For info on V2 please see [here](#V2)
Minimally invasive meaning that users will use only Ktor native functions when implementing their API, and will
supplement with Kompendium code in order to generate the appropriate spec. Kompendium is intended to be a minimally invasive OpenApi Specification generator for [Ktor](https://ktor.io).
Minimally invasive meaning that users will use only Ktor native functions when implementing their API, and will
supplement with Kompendium code in order to generate the appropriate spec.
## How to install ## How to install
Kompendium publishes all releases to Maven Central. As such, using the stable version of `Kompendium` is as simple Kompendium publishes all releases to Maven Central. As such, using the stable version of `Kompendium` is as simple
as declaring it as an implementation dependency in your `build.gradle.kts` as declaring it as an implementation dependency in your `build.gradle.kts`
```kotlin ```kotlin
@ -31,8 +33,8 @@ dependencies {
The last two dependencies are optional. The last two dependencies are optional.
If you want to get a little spicy 🤠 every merge of Kompendium is published to the GitHub package registry. Pulling If you want to get a little spicy 🤠 every merge of Kompendium is published to the GitHub package registry. Pulling
from GitHub is slightly more involved, but such is the price you pay for bleeding edge fake data generation. from GitHub is slightly more involved, but such is the price you pay for bleeding edge fake data generation.
```kotlin ```kotlin
// 1 Setup a helper function to import any Github Repository Package // 1 Setup a helper function to import any Github Repository Package
@ -60,14 +62,14 @@ dependencies {
## Local Development ## Local Development
Kompendium should run locally right out of the box, no configuration necessary (assuming you have JDK 1.8+ installed). New features can be built locally and published to your local maven repository with the `./gradlew publishToMavenLocal` command! Kompendium should run locally right out of the box, no configuration necessary (assuming you have JDK 1.8+ installed). New features can be built locally and published to your local maven repository with the `./gradlew publishToMavenLocal` command!
## In depth ## In depth
### Notarized Routes ### Notarized Routes
Kompendium introduces the concept of `notarized` HTTP methods. That is, for all your `GET`, `POST`, `PUT`, and `DELETE` Kompendium introduces the concept of `notarized` HTTP methods. That is, for all your `GET`, `POST`, `PUT`, and `DELETE`
operations, there is a corresponding `notarized` method. These operations are strongly typed, and use reification for operations, there is a corresponding `notarized` method. These operations are strongly typed, and use reification for
a lot of the class based reflection that powers Kompendium. Generally speaking the three types that a `notarized` method a lot of the class based reflection that powers Kompendium. Generally speaking the three types that a `notarized` method
will consume are will consume are
@ -79,54 +81,54 @@ will consume are
In addition to standard HTTP Methods, Kompendium also introduced the concept of `notarizedExceptions`. Using the `StatusPage` In addition to standard HTTP Methods, Kompendium also introduced the concept of `notarizedExceptions`. Using the `StatusPage`
extension, users can notarize all handled exceptions, along with their respective HTTP codes and response types. extension, users can notarize all handled exceptions, along with their respective HTTP codes and response types.
Exceptions that have been `notarized` require two types as supplemental information Exceptions that have been `notarized` require two types as supplemental information
- `TErr`: Used to notarize the exception being handled by this use case. Used for matching responses at the route level. - `TErr`: Used to notarize the exception being handled by this use case. Used for matching responses at the route level.
- `TResp`: Same as above, this dictates the expected return type of the error response. - `TResp`: Same as above, this dictates the expected return type of the error response.
In keeping with minimal invasion, these extension methods all consume the same code block as a standard Ktor route method, In keeping with minimal invasion, these extension methods all consume the same code block as a standard Ktor route method,
meaning that swapping in a default Ktor route and a Kompendium `notarized` route is as simple as a single method change. meaning that swapping in a default Ktor route and a Kompendium `notarized` route is as simple as a single method change.
### Supplemental Annotations ### Supplemental Annotations
In general, Kompendium tries to limit the number of annotations that developers need to use in order to get an app In general, Kompendium tries to limit the number of annotations that developers need to use in order to get an app
integrated. integrated.
Currently, the annotations used by Kompendium are as follows Currently, the annotations used by Kompendium are as follows
- `KompendiumField` - `KompendiumField`
- `KompendiumParam` - `KompendiumParam`
The intended purpose of `KompendiumField` is to offer field level overrides such as naming conventions (ie snake instead of camel). The intended purpose of `KompendiumField` is to offer field level overrides such as naming conventions (ie snake instead of camel).
The purpose of `KompendiumParam` is to provide supplemental information needed to properly assign the type of parameter The purpose of `KompendiumParam` is to provide supplemental information needed to properly assign the type of parameter
(cookie, header, query, path) as well as other parameter-level metadata. (cookie, header, query, path) as well as other parameter-level metadata.
### Undeclared Field ### Undeclared Field
There is also a final `UndeclaredField` annotation. This should be used only in an absolutely emergency. This annotation There is also a final `UndeclaredField` annotation. This should be used only in an absolutely emergency. This annotation
will allow you to inject a _single_ undeclared field that will be included as part of the schema. will allow you to inject a _single_ undeclared field that will be included as part of the schema.
Due to limitations in using repeated annotations, this can only be used once per class Due to limitations in using repeated annotations, this can only be used once per class
This is a complete hack, and is included for odd scenarios like kotlinx serialization polymorphic adapters that expect a This is a complete hack, and is included for odd scenarios like kotlinx serialization polymorphic adapters that expect a
`type` field in order to perform their analysis. `type` field in order to perform their analysis.
Use this _only_ when **all** else fails Use this _only_ when **all** else fails
### Polymorphism ### Polymorphism
Speaking of polymorphism... out of the box, Kompendium has support for sealed classes and interfaces. At runtime, it will build a mapping of all available sub-classes Speaking of polymorphism... out of the box, Kompendium has support for sealed classes and interfaces. At runtime, it will build a mapping of all available sub-classes
and build a spec that takes `anyOf` the implementations. This is currently a weak point of the entire library, and and build a spec that takes `anyOf` the implementations. This is currently a weak point of the entire library, and
suggestions on better implementations are welcome 🤠 suggestions on better implementations are welcome 🤠
### Serialization ### Serialization
Under the hood, Kompendium uses Jackson to serialize the final api spec. However, this implementation detail Under the hood, Kompendium uses Jackson to serialize the final api spec. However, this implementation detail
does not leak to the actual API, meaning that users are free to choose the serialization library of their choice. does not leak to the actual API, meaning that users are free to choose the serialization library of their choice.
Added the possibility to add your own ObjectMapper for Jackson. Added the possibility to add your own ObjectMapper for Jackson.
Added a default parameter with the following configuration: Added a default parameter with the following configuration:
@ -153,11 +155,11 @@ routing {
> ⚠️ Warning: Custom route handling is almost definitely an indication that either a new selector should be added to kompendium-core or that kompendium is in need of another module to handle a new ktor companion module. If you have encountered a route selector that is not already handled, please consider opening an [issue](https://github.com/bkbnio/kompendium/issues/new) > ⚠️ Warning: Custom route handling is almost definitely an indication that either a new selector should be added to kompendium-core or that kompendium is in need of another module to handle a new ktor companion module. If you have encountered a route selector that is not already handled, please consider opening an [issue](https://github.com/bkbnio/kompendium/issues/new)
Kompendium does its best to handle all Ktor routes out of the gate. However, in keeping with the modular approach of Kompendium does its best to handle all Ktor routes out of the gate. However, in keeping with the modular approach of
Ktor and Kompendium, this is not always possible. Ktor and Kompendium, this is not always possible.
Should you need to, custom route handlers can be registered via the Should you need to, custom route handlers can be registered via the
`Kompendium.addCustomRouteHandler` function. `Kompendium.addCustomRouteHandler` function.
The handler signature is as follows The handler signature is as follows
@ -169,7 +171,7 @@ fun <T : RouteSelector> addCustomRouteHandler(
``` ```
This function takes a selector, which _must_ be a KClass of the Ktor `RouteSelector` type. The handler is a function This function takes a selector, which _must_ be a KClass of the Ktor `RouteSelector` type. The handler is a function
that extends the Kompendium `PathCalculator`. This is necessary because it gives you access to `PathCalculator.calculate`, that extends the Kompendium `PathCalculator`. This is necessary because it gives you access to `PathCalculator.calculate`,
which you are going to want in order to recursively calculate the remainder of the route :) which you are going to want in order to recursively calculate the remainder of the route :)
Its parameters are the `Route` itself, along with the "tail" of the Path (the path that has been calculated thus far). Its parameters are the `Route` itself, along with the "tail" of the Path (the path that has been calculated thus far).
@ -178,7 +180,7 @@ Working examples `init` blocks of the `PathCalculator` and `KompendiumAuth` obje
## Examples ## Examples
The full source code can be found in the `kompendium-playground` module. Here is a simple get endpoint example The full source code can be found in the `kompendium-playground` module. Here is a simple get endpoint example
```kotlin ```kotlin
// Minimal API Example // Minimal API Example
@ -219,7 +221,7 @@ val simpleGetInfo = GetInfo<Unit, ExampleResponse>(
### Kompendium Auth and security schemes ### Kompendium Auth and security schemes
There is a separate library to handle security schemes: `kompendium-auth`. There is a separate library to handle security schemes: `kompendium-auth`.
This needs to be added to your project as dependency. This needs to be added to your project as dependency.
At the moment, the basic and jwt authentication is only supported. At the moment, the basic and jwt authentication is only supported.
@ -275,7 +277,7 @@ Minimal Example:
``` ```
### Enabling ReDoc ### Enabling ReDoc
Unlike swagger, redoc is provided (perhaps confusingly, in the `core` module). This means out of the box with `kompendium-core`, you can add Unlike swagger, redoc is provided (perhaps confusingly, in the `core` module). This means out of the box with `kompendium-core`, you can add
[ReDoc](https://github.com/Redocly/redoc) as follows [ReDoc](https://github.com/Redocly/redoc) as follows
```kotlin ```kotlin
@ -287,20 +289,20 @@ routing {
## Custom Type Overrides ## Custom Type Overrides
Kompendium does its best to analyze types and to generate an OpenAPI format accordingly. However, there are certain Kompendium does its best to analyze types and to generate an OpenAPI format accordingly. However, there are certain
classes that just don't play nice with the standard reflection analysis that Kompendium performs. classes that just don't play nice with the standard reflection analysis that Kompendium performs.
Should you encounter a data type that Kompendium cannot comprehend, you will need to Should you encounter a data type that Kompendium cannot comprehend, you will need to
add it explicitly. For example, adding the Joda Time `DateTime` object would be as simple as the following add it explicitly. For example, adding the Joda Time `DateTime` object would be as simple as the following
```kotlin ```kotlin
Kompendium.addCustomTypeSchema(DateTime::class, FormatSchema("date-time", "string")) Kompendium.addCustomTypeSchema(DateTime::class, FormatSchema("date-time", "string"))
``` ```
Since `Kompendium` is an object, this needs to be declared once, ahead of the actual API instantiation. This way, this Since `Kompendium` is an object, this needs to be declared once, ahead of the actual API instantiation. This way, this
type override can be cached ahead of reflection. Kompendium will then match all instances of this type and return the type override can be cached ahead of reflection. Kompendium will then match all instances of this type and return the
specified schema. specified schema.
So how do you know a type can and cannot be inferred? The safe bet is that it can be. So go ahead and give it a shot. So how do you know a type can and cannot be inferred? The safe bet is that it can be. So go ahead and give it a shot.
However, in the very odd scenario (almost always having to do with date/time libraries 😤) where it can't, you can rest However, in the very odd scenario (almost always having to do with date/time libraries 😤) where it can't, you can rest
safely knowing that you have the option to inject a custom override should you need to. safely knowing that you have the option to inject a custom override should you need to.
@ -310,18 +312,24 @@ safely knowing that you have the option to inject a custom override should you n
Currently, Kompendium exists as a Kotlin object. This comes with a couple perks, but a couple downsides. Primarily, Currently, Kompendium exists as a Kotlin object. This comes with a couple perks, but a couple downsides. Primarily,
it offers a seriously clean UX where the implementer doesn't need to worry about what instance to send data to. The main it offers a seriously clean UX where the implementer doesn't need to worry about what instance to send data to. The main
drawback, however, is that you are limited to a single API per classpath. drawback, however, is that you are limited to a single API per classpath.
If this is a blocker, please open a GitHub issue, and we can start to think out solutions! If this is a blocker, please open a GitHub issue, and we can start to think out solutions!
## Future Work ## Future Work
Work on V1 of Kompendium has come to a close. This, however, does not mean it has achieved complete Work on V1 of Kompendium has come to a close. This, however, does not mean it has achieved complete
parity with the OpenAPI feature spec, nor does it have all-of-the nice to have features that a truly next-gen API spec parity with the OpenAPI feature spec, nor does it have all-of-the nice to have features that a truly next-gen API spec
should have. There are several outstanding features that have been added to the should have. There are several outstanding features that have been added to the
[V2 Milestone](https://github.com/bkbnio/kompendium/milestone/2). Among others, this includes [V2 Milestone](https://github.com/bkbnio/kompendium/milestone/2). Among others, this includes
- AsyncAPI Integration - AsyncAPI Integration
- Field Validation - Field Validation
If you have a feature that you would like to see implemented that is not on this list, or discover a 🐞, please open If you have a feature that you would like to see implemented that is not on this list, or discover a 🐞, please open
an issue [here](https://github.com/bkbnio/kompendium/issues/new) an issue [here](https://github.com/bkbnio/kompendium/issues/new)
### V2
Due to the large number of breaking changes that will be made in version 2, development is currently being done on the
long-lived `v2` feature branch. If you are working on any feature in the `V2` milestone, please target that branch!
If you are unsure where your changes should be, please open an issue first :)