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.

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.

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. 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.

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.

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.

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

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.

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.

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>()
  }
}