Kopapi is library to generate OpenAPI documentation from Ktor routes.

---

Quick sample usage before diving into the Wiki:

get("/items/{data_id}") {
    // Implement as usual
} api {
    tags = setOf("Items", "Data")
    summary = "Retrieve data items."
    description = "Fetches all items for a group."
    operationId = "getDataItems"
    pathParameter<Uuid>("data_id") { description = "The data set Id." }
    queryParameter<String>("item_id") { description = "Optional item Id to locate." }
    response<List<Item>>(status = HttpStatusCode.OK) { description = "Successful fetch." }
    response(status = HttpStatusCode.NotFound) { description = "Data not found." }
    bearerSecurity(name = "Authentication") { description = "Access to data." }
}

Characteristics:

• Lightweight and minimally invasive integration.
• Provides Swagger UI and ReDoc out of the box for testing and documentation.
• Flexible and expressive DSL builder.
• No unnatural modifications to your routes. Just add the api documentation block after it.
• Support for arbitrary types, including generics, collections and complex nested structures.
• Support for Kotlinx and Jackson annotations (under development).
• Generate schema outputs in YAML or JSON format.
• Well documented.

---

Installation

Add the library to your project gradle dependencies.

dependencies {
    implementation("io.github.perracodex:kopapi:<VERSION>>")
}

Version Compatibility

Kopapi	Ktor
1.0.5	>= 3.0.0

---

Wiki

• Plugin

  • Plugin Configuration

  • Servers

  • Security

  • Top Level Tags

• API

  • API Usage

  • Summary and Description

  • Path Operation Tags

  • Parameters

  • Request Bodies

  • Responses

  • Security

  • Servers

  • Schema Annotation

  • Path-Level Metadata

• Internals

  • Debug Panel

  • Type Conflicts

  • Type Introspection

• Examples

  • Plugin Setup

  • Basic Request

  • Multiple Responses

  • RequestBody

  • Multipart

  • Security

  • Schema Annotation

---

To see the library in action, check the Kcrud repository:

• https://github.com/perracodex/kcrud/blob/main/kcrud-core/src/main/kotlin/kcrud/core/plugins/ApiSchema.kt
• https://github.com/perracodex/kcrud/tree/main/kcrud-employee/src/main/kotlin/kcrud/domain/employee/api
• https://github.com/perracodex/kcrud/tree/main/kcrud-access/src/main/kotlin/kcrud/access/token/api/operate
• https://github.com/perracodex/kcrud/tree/main/kcrud-access/src/main/kotlin/kcrud/access/rbac/api
• https://github.com/perracodex/kcrud/tree/main/kcrud-core/src/main/kotlin/kcrud/core/scheduler/api

---

License

This project is licensed under the Apache 2.0 License - see the LICENSE file for details.