kompendium/docs/plugins/notarized_route.md

The `NotarizedRoute` plugin is the method by which you define the functionality and metadata for an individual route of
your API.

# Route Level Metadata

## Route Tags

OpenAPI uses the concept of tags in order to logically group operations. Tags defined at the `NotarizedRoute` level will
be applied to _all_ operations defined in this route. In order to define tags for a specific operation,
see [below](#operation-tags).

```kotlin
private fun Route.documentation() {
  install(NotarizedRoute()) {
    tags = setOf("User")
    // will apply the User tag to all operations defined below
  }
}
```

## Route Parameters

Parameters can be defined at the route level. Doing so will assign the parameters to _all_ operations defined in this
route. In order to define parameters for a specific operation, see [below](#operation-parameters).

```kotlin
private fun Route.documentation() {
  install(NotarizedRoute()) {
    parameters = listOf(
      Parameter(
        name = "id",
        `in` = Parameter.Location.path,
        schema = TypeDefinition.STRING
      )
    )
    // Will apply the id parameter to all operations defined below
  }
}
```

# Defining Operations

Obviously, our route documentation would not be very useful without a way to detail the operations that are available at
the specified route. These operations will take the metadata defined, along with any existing info present at the route
level detailed [above](#route-level-metadata). Together, this defines an OpenAPI path operation.

## Operation Builders

Each HTTP Operation (Get, Put Post, Patch, Delete, Head, Options) has its own `Builder` that Kompendium uses to define
the necessary information to associate with the detailed operation. For example, a simple `GET` request could be
defined as follows.

```kotlin
install(NotarizedRoute()) {
  get = GetInfo.builder {
    summary("Get ImportantDetail")
    description("Retrieves an Important Detail from the database")
    response {
      responseCode(HttpStatusCode.OK)
      responseType<TestResponse>()
      description("The Detail in Question")
    }
  }
}
```

## Operation Tags

Operation tags work much like route tags, except they only apply to the operation they are defined in. They are defined
slightly differently, as a function on the builder, rather than an instance variable directly.

```kotlin
install(NotarizedRoute()) {
  get = GetInfo.builder {
    tags("User")
    // ...
  }
}
```

## Operation Parameters

Operation parameters work much like route parameters, except they only apply to the operation they are defined in. They
are defined slightly differently, as a function on the builder, rather than an instance variable directly.

```kotlin
install(NotarizedRoute()) {
  get = GetInfo.builder {
    parameters(
      Parameter(
        name = "a",
        `in` = Parameter.Location.path,
        schema = TypeDefinition.STRING,
      ),
      Parameter(
        name = "aa",
        `in` = Parameter.Location.query,
        schema = TypeDefinition.INT
      )
    )
    // ...
  }
}
```

## Response Info

All operations are required to define a response info block, detailing the standard response that users of the API
should expect when performing this operation. At its most simple, doing so looks like the following

```kotlin
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 😱")
  }
}
```

As you can see, we attach an http status code, a description, and finally the type that represents the payload that
users should expect. In order to indicate that no payload is expected, use `responseType<Unit>()`. This should typically
be paired with a `204` status code.

## Request Info

On operations that allow a request body to be associated, you must also define a response info block so that Kompendium
can determine how to populate the required operation data.

```kotlin
post = PostInfo.builder {
  summary("Create User")
  description("Will create a new user entity")
  request {
    requestType<CreateUserRequest>()
    description("Data required to create new user")
  }
  response {
    responseCode(HttpStatusCode.Created)
    responseType<UserCreatedResponse>()
    description("User was created successfully")
  }
}
```

## Error Info

In addition to the standard response, you can attach additional responses via the `canRespond` function.

```kotlin
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 😱")
  }
  canRespond {
    description("Bad Things Happened")
    responseCode(HttpStatusCode.InternalServerError)
    responseType<ExceptionResponse>()
  }
}
```

## Media Types

By default, Kompendium will set the only media type to "application/json".  If you would like to override the media type 
for a specific request or response (including errors), you can do so with the `mediaTypes` method

```kotlin
get = GetInfo.builder {
  summary("Get user by id")
  description("A very neat endpoint!")
  response {
    mediaTypes("application/xml")
    responseCode(HttpStatusCode.OK)
    responseType<ExampleResponse>()
    description("Will return whether or not the user is real 😱")
  }
}
```

## Partial Authentication

One might want to have a public GET endpoint but a protected PUT endpoint. This can be achieved by registering two
separate notarized routes. Note that you will get an error if you try to register the same method twice, as each path
can only have one registration per method. Example:

```kotlin
route("/user/{id}") {
  get = GetInfo.builder {
    // ...
  }
  // ...
  authenticate {
    put = PutInfo.builder {
      // ...
    }
    // ...
  }
}
```