README.md

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:

• Minimally invasive integration.
• Provides Swagger UI and ReDoc out of the box.
• Flexible and expressive DSL builder.
• No unnatural modifications to the routes.
• Support for arbitrary types, including generics, collections and complex nested structures.
• Support for Kotlinx and Jackson annotations (under development).
• 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	Kotlin
1.0.9	>= 3.0.3	>= 2.1.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 Krud repository:

• https://github.com/perracodex/krud/blob/main/krud-core/base/src/main/kotlin/krud/base/plugins/ApiSchema.kt
• https://github.com/perracodex/krud/tree/main/krud-domain/employee/src/main/kotlin/krud/domain/employee/api
• https://github.com/perracodex/krud/tree/main/krud-core/access/src/main/kotlin/krud/access/domain/token/api

---

License

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