kompendium
2.0.1
2.0.2 2.0.1

# Package io.bkbn.kompendium.core

The root package contains several objects that power Kompendium, including the Kompendium Ktor Plugin, route notarization methods, and the reflection engine that analyzes method info type parameters.

## Plugin

The Kompendium plugin is an extremely light-weight plugin, with only a couple areas of customization.

### Serialization

Kompendium relies on your API to provide a properly-configured `ContentNegotiator` in order to convert the `OpenApiSpec` into JSON. The advantage to this approach is that all of your data classes will be serialized precisely how you define. The downside is that issues could exist in serialization frameworks that have not been tested. At the moment, Jackson, Gson and KotlinX serialization have all been tested. If you run into any serialization issues, particularly with a serializer not listed above, please open an issue on GitHub 🙏

## Notarization

Central to Kompendium is the concept of notarization.

Notarizing a route is the mechanism by which Kompendium analyzes your route types, along with provided metadata, and converts to the expected OpenAPI format.

Before jumping into notarization, lets first look at a standard Ktor route

    routing {
      get {
        call.respond(HttpStatusCode.OK, BasicResponse(c = UUID.randomUUID().toString()))
      }
    }

Content copied to clipboard

Now, let's compare this to the same functionality, but notarized using Kompendium

    routing {
      notarizedGet(simpleGetExample) {
        call.respond(HttpStatusCode.OK, BasicResponse(c = UUID.randomUUID().toString()))
      }
    }

Content copied to clipboard

Pretty simple huh. But hold on... what is this `simpleGetExample`? How can I know that it is so "simple". Let's take a look

    val simpleGetExample = GetInfo<Unit, BasicResponse>(
      summary = "Simple, Documented GET Request",
      description = "This is to showcase just how easy it is to document your Ktor API!",
      responseInfo = ResponseInfo(
        status = HttpStatusCode.OK,
        description = "This means everything went as expected!",
        examples = mapOf("demo" to BasicResponse(c = "52c099d7-8642-46cc-b34e-22f39b923cf4"))
      ),
      tags = setOf("Simple")
    )

Content copied to clipboard

See, not so bad 😄 `GetInfo<*,*>` is an implementation of `MethodInfo<TParam, TResp>`, a sealed interface designed to encapsulate all the metadata required for documenting an API route. Kompendium leverages this data, along with the provided type parameters `TParam` and `TResp` to construct the full OpenAPI Specification for your route.

Additionally, just as a backup, each notarization method includes a "post-processing' hook that will allow you to have final say in the generated route info prior to being attached to the spec. This can be accessed via the optional parameter

    routing {
      notarizedGet(simpleGetExample, postProcess = { spec -> spec }) {
        call.respond(HttpStatusCode.OK, BasicResponse(c = UUID.randomUUID().toString()))
      }
    }

Content copied to clipboard

This should only be used in extremely rare scenarios, but it is nice to know it is there if you need it.

## Types

Kompendium
Link copied to clipboard
class Kompendium (config: Kompendium.Configuration )
Content copied to clipboard
KompendiumPreFlight
Link copied to clipboard
object KompendiumPreFlight
Content copied to clipboard

Functions are considered preflight when they are used to intercept a method ahead of running.

Kontent
Link copied to clipboard
object Kontent
Content copied to clipboard

Responsible for generating the schema map that is used to power all object references across the API Spec.

Notarized
Link copied to clipboard
object Notarized
Content copied to clipboard

Notarization methods are the primary way that a Ktor API using Kompendium differentiates from a default Ktor application. On instantiation, a notarized route, provided with the proper metadata, will reflectively analyze all pertinent data to build a corresponding OpenAPI entry.