chore: rollback docs due to sonatype disaster (#581)

This commit is contained in:
Ryan Brink
2024-03-06 10:16:00 -05:00
committed by GitHub
parent 889fdb41d7
commit dcde50de0a
6 changed files with 140 additions and 131 deletions

View File

@ -20,22 +20,21 @@ reference [OpenAPI spec](https://spec.openapis.org/oas/v3.1.0) itself.
For public facing APIs, having the default endpoint exposed at `/openapi.json` is totally fine. However, if you need
more granular control over the route that exposes the generated schema, you can modify the `openApiJson` config value.
For example, if we want to hide our schema behind a basic auth check with a custom json encoder, we could do the
following
For example, if we want to hide our schema behind a basic auth check, we could do the following
```kotlin
private fun Application.mainModule() {
// Install content negotiation, auth, etc...
install(NotarizedApplication()) {
// ...
specRoute = { spec, routing ->
routing {
authenticate("basic") {
route("/openapi.json") {
get {
call.response.headers.append("Content-Type", "application/json")
call.respondText { CustomJsonEncoder.encodeToString(spec) }
}
openApiJson = {
authenticate("basic") {
route("/openapi.json") {
get {
call.respond(
HttpStatusCode.OK,
this@route.application.attributes[KompendiumAttributes.openApiSpec]
)
}
}
}
@ -75,14 +74,32 @@ This means that we only need to define our custom type once, and then Kompendium
application.
> While intended for custom scalars, there is nothing stopping you from leveraging custom types to circumvent type
> analysis on any class you choose. If you have an alternative method of generating JsonSchema definitions, you could
> put them all in this map and effectively prevent Kompendium from having to do any reflection
> analysis
> on any class you choose. If you have an alternative method of generating JsonSchema definitions, you could put them
> all
> in this map and effectively prevent Kompendium from having to do any reflection
## Schema Configurator
Out of the box, Kompendium supports KotlinX serialization... however, in order to allow for users of other
serialization libraries to use Kompendium, we have provided a `SchemaConfigurator` interface that allows you to
configure how Kompendium will generate schema definitions.
The `SchemaConfigurator` is an interface that allows users to bridge the gap between Kompendium serialization and custom
serialization strategies that the serializer they are using for their API. For example, if you are using KotlinX
serialization in order to convert kotlin fields from camel case to snake case, you could leverage
the `KotlinXSchemaConfigurator` in order to instruct Kompendium on how to serialize values properly.
For an example of the `SchemaConfigurator` in action, please see the `KotlinxSchemaConfigurator`. This will give you
a good idea of the additional functionality it can add based on your own serialization needs.
```kotlin
private fun Application.mainModule() {
install(ContentNegotiation) {
json(Json {
serializersModule = KompendiumSerializersModule.module
encodeDefaults = true
explicitNulls = false
})
}
install(NotarizedApplication()) {
spec = baseSpec
// Adds support for @Transient and @SerialName
// If you are not using them this is not required.
schemaConfigurator = KotlinXSchemaConfigurator()
}
}
```