Browse Source

update README, add documentation

main
James Fenn 8 months ago
parent
commit
2bba75a91d
6 changed files with 94 additions and 4 deletions
  1. +65
    -4
      README.md
  2. +11
    -0
      docs/src/me/jfenn/ktordocs/RestDocsFeature.kt
  3. +4
    -0
      docs/src/me/jfenn/ktordocs/interface/HasParams.kt
  4. +3
    -0
      docs/src/me/jfenn/ktordocs/interface/HasReferences.kt
  5. +3
    -0
      docs/src/me/jfenn/ktordocs/model/EndpointInfo.kt
  6. +8
    -0
      docs/src/me/jfenn/ktordocs/model/ResponseInfo.kt

+ 65
- 4
README.md View File

@@ -1,4 +1,4 @@
Ktor-Docs [![JitPack](https://jitpack.io/v/dev.horrific.code.james/git-rest-wrapper.svg)](https://jitpack.io/#dev.horrific.code.james/ktordocs) [![Discord](https://img.shields.io/discord/514625116706177035.svg?logo=discord&colorB=7289da)](https://discord.jfenn.me/)
Ktor-Docs [![JitPack](https://jitpack.io/v/dev.horrific.code.james/ktordocs.svg)](https://jitpack.io/#dev.horrific.code.james/ktordocs) [![Discord](https://img.shields.io/discord/514625116706177035.svg?logo=discord&colorB=7289da)](https://discord.jfenn.me/)
=====

This library automatically generates REST API documentation for Ktor/JVM projects and hosts it under a specified URL.
@@ -24,13 +24,13 @@ implementation "dev.horrific.code.james:ktordocs:$ktordocs_version"

## Usage

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.

+ 11
- 0
docs/src/me/jfenn/ktordocs/RestDocsFeature.kt View File

@@ -116,6 +116,10 @@ class RestDocsFeature(

}

/**
* Hosts the API documentation generated by the library
* at the specified path.
*/
fun Route.restDocumentation(path: String = "/") {
GlobalScope.launch {
delay(500)
@@ -129,6 +133,13 @@ fun Route.restDocumentation(path: String = "/") {
}
}

/**
* Provides documentation for a particular endpoint.
* Should be invoked at the start of the request handler.
*
* Under normal conditions, this function call does
* nothing.
*/
fun PipelineContext<Unit, ApplicationCall>.docs(configure: EndpointInfo.() -> Unit) {
if (this is DummyPipelineContext)
throw DocsProxyException(configure)


+ 4
- 0
docs/src/me/jfenn/ktordocs/interface/HasParams.kt View File

@@ -6,6 +6,10 @@ interface HasParams {

val params: HashMap<String, ParameterInfo>

/**
* Provide information about a parameter or argument of a
* particular endpoint / request.
*/
fun param(name: String, configure: ParameterInfo.() -> Unit = {}) {
params[name] = (params[name] ?: ParameterInfo(name)).apply { configure() }
}


+ 3
- 0
docs/src/me/jfenn/ktordocs/interface/HasReferences.kt View File

@@ -6,6 +6,9 @@ interface HasReferences {

val references: ArrayList<ReferenceInfo>

/**
* Reference a link or URL.
*/
fun reference(url: String, title: String = url) {
references.add(ReferenceInfo(url, title))
}


+ 3
- 0
docs/src/me/jfenn/ktordocs/model/EndpointInfo.kt View File

@@ -21,6 +21,9 @@ class EndpointInfo(
override val params = HashMap<String, ParameterInfo>()
internal val responses = HashMap<HttpStatusCode, ResponseInfo>()

/**
* Specify a particular response behavior of the current endpoint.
*/
fun responds(code: HttpStatusCode = HttpStatusCode.OK, configure: ResponseInfo.() -> Unit = {}) {
responses[code] = (responses[code] ?: ResponseInfo(code)).apply { configure() }
}


+ 8
- 0
docs/src/me/jfenn/ktordocs/model/ResponseInfo.kt View File

@@ -11,6 +11,14 @@ data class ResponseInfo(
var example: String? = null
) {

/**
* Create an "example" JSON preview based on the
* provided data class.
*
* (this is intended for when there is a specific
* data class which is passed through a serializer
* to provide a response)
*/
fun exampleJson(type: KClass<*>) {
example = buildString {
appendln("{")


Loading…
Cancel
Save