Home

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." }
  defaultResponse { description = "Unexpected issue." }
  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.15	>= 3.3.0	>= 2.2.20
1.0.14	>= 3.2.3	>= 2.2.0
1.0.13	>= 3.1.2	>= 2.1.20
1.0.12	= 3.1.1	= 2.1.10

---

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 MIT License - see the LICENSE file for details.