First, you must install the ktor feature - replacing the configuration with your project's values.
First, you must install the ktor feature - replacing the default configuration with your project's values.
```kotlin
install(RestDocsFeature) {
baseUrl = "https://example.com"
title = "Example API"
description = "Basic documentation generated for testing & demo purposes."
desc = "Basic documentation generated for testing & demo purposes."
}
```
@@ -40,7 +40,7 @@ Documentation can then be specified in any endpoint/request handler by invoking
get("/api/v1/example") {
docs {
title = "Hello World"
description = "Says hello to the world."
desc = "Says hello to the world."
}
call.respondText("Hello world!")
@@ -55,6 +55,67 @@ route("/api") {
}
```
### Endpoint Parameters
The library will automatically generate a list of URL parameters by parsing the endpoint URL - however, more information can be specified using the `param(...)` function...
```kotlin
get("/api/user/{username}") {
docs {
param("username") { // a URL property
type = "SHA1 hash"
desc = "A unique identifier of a user."
}
param("fetchAll") { // a query parameter (/?fetchAll=true)
type = "boolean"
desc = "Whether to fetch all user information from external sources."
location = ParameterInfo.In.Query
}
}
// ...
}
```
### Endpoint Responses
Some endpoints may return different information depending on the response status - such as an error handler or authentication state. This can be specified using the `responds()` function.
```kotlin
get("/api/user/{username}") {
docs {
responds { // default response behavior (200 OK)
desc = "If the user has been found."
// this is a handy function to set the `example` property
// if your response uses a JSON serializer
exampleJson(UserInfo::class)
}
responds(HttpStatusCode.NotFound) {
desc = "If the user doesn't exist."
example = """{ "message": "Unable to locate the requested user." }"""
}
}
// ...
}
```
### Links
Endpoints can reference URL links as supporting material, which are provided in a list on the documentation page.
```kotlin
get("/api/user/{username}") {
docs {
reference("https://example.com")
reference("https://example.com", "Example Link")
}
// ...
}
```
## Development
The project uses Gradle builds for... err... most things. `./gradlew :{module}:test` and `./gradle :{module}:run` are fairly universal.
