Kompendium is intended to be a non-invasive OpenAPI spec generator for [Ktor](https://ktor.io) APIs. By operating
entirely through Ktor's plugin architecture, Kompendium allows you to incrementally document your API without requiring
you to rip out and replace the amazing code you have already written.

# Compatibility

| Kompendium | Ktor | OpenAPI | 
|------------|------|---------|
| 1.X        | 1    | 3.0     |
| 2.X        | 1    | 3.0     |
| 3.X        | 2    | 3.1     | 

> These docs are focused solely on Kompendium 3, previous versions should be considered deprecated and no longer
> maintained

# Getting Started

## Adding the Artifact

All Kompendium artifacts are published to Maven Central. Most Kompendium users will only need to import the core
dependency

```kotlin
dependencies {
  // other dependencies...
  implementation("io.bkbn:kompendium-core:latest.release")
}
```

## Notarizing a Ktor Application

Once we have added the dependencies, installed the `NotarizedApplication` plugin. This is an application-level
Ktor plugin that is used to instantiate and configure Kompendium. Your OpenAPI spec metadata will go here, along with
custom type overrides (typically useful for custom scalars such as dates and times), along with other configurations.

```kotlin
private fun Application.mainModule() {
  install(NotarizedApplication()) {
    spec = {
        OpenApiSpec(
        // ...
      )
    }
  }
}
```

At this point, you will have a valid OpenAPI specification generated at runtime, which can be accessed by default
at the `/openapi.json` path of your api.

For more detail on the `NotarizedApplication` plugin, please see the [docs](./plugins/notarized_application.md)

## Notarizing a Ktor Route

Once you have notarized your application, you can begin to notarize individual routes using the `NotarizedRoute` plugin.
This is a route-level Ktor plugin that is used to configure the documentation for a specific endpoint of your API. The
route documentation will be piped back to the application-level plugin, and will be automatically injected into the
OpenApi specification.

Setting up documentation on a route is easiest achieved by creating an extension function on the Ktor `Route` class

```kotlin
private fun Route.documentation() {
  install(NotarizedRoute()) {
    parameters = listOf(
      Parameter(
        name = "id",
        `in` = Parameter.Location.path,
        schema = TypeDefinition.STRING
      )
    )
    get = GetInfo.builder {
      summary("Get user by id")
      description("A very neat endpoint!")
      response {
        responseCode(HttpStatusCode.OK)
        responseType<ExampleResponse>()
        description("Will return whether or not the user is real 😱")
      }
    }
  }
}
```

Once you have created your documentation function, it can be attached to the route simply by calling it at the desired
path.

```kotlin
private fun Application.mainModule() {
  // ...
  routing {
    // ... 
    route("/{id}") {
      documentation()
      get {
        // ...
      }
    }
  }
}
```

For more details on the `NotarizedRoute` plugin, please see the [docs](./plugins/notarized_route.md)