docs: initial gitbook docs (#336)

docs/plugins/notarized_route.md

@@ -0,0 +1,167 @@
+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>()
+  }
+}
+```