{"id":18550706,"url":"https://github.com/smiley4/ktor-swagger-ui","last_synced_at":"2025-02-26T19:05:41.138Z","repository":{"id":59552844,"uuid":"526907299","full_name":"SMILEY4/ktor-swagger-ui","owner":"SMILEY4","description":"Kotlin Ktor plugin to generate OpenAPI and provide Swagger UI","archived":false,"fork":false,"pushed_at":"2025-02-13T18:06:37.000Z","size":4794,"stargazers_count":204,"open_issues_count":7,"forks_count":34,"subscribers_count":4,"default_branch":"develop","last_synced_at":"2025-02-19T18:03:26.628Z","etag":null,"topics":["kotlin","ktor","ktor-plugin","openapi","swagger","swagger-ui"],"latest_commit_sha":null,"homepage":"","language":"Kotlin","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/SMILEY4.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-08-20T11:29:42.000Z","updated_at":"2025-02-17T21:20:42.000Z","dependencies_parsed_at":"2024-03-19T13:29:17.929Z","dependency_job_id":"f067f80d-4a76-4dd2-8077-a0468fcd7d38","html_url":"https://github.com/SMILEY4/ktor-swagger-ui","commit_stats":{"total_commits":313,"total_committers":19,"mean_commits":"16.473684210526315","dds":"0.20127795527156545","last_synced_commit":"12cfd091348271776f72fa1acb6c2214542b1d16"},"previous_names":[],"tags_count":69,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SMILEY4%2Fktor-swagger-ui","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SMILEY4%2Fktor-swagger-ui/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SMILEY4%2Fktor-swagger-ui/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SMILEY4%2Fktor-swagger-ui/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/SMILEY4","download_url":"https://codeload.github.com/SMILEY4/ktor-swagger-ui/tar.gz/refs/heads/develop","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":240917707,"owners_count":19878308,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["kotlin","ktor","ktor-plugin","openapi","swagger","swagger-ui"],"created_at":"2024-11-06T21:05:31.975Z","updated_at":"2025-02-26T19:05:41.131Z","avatar_url":"https://github.com/SMILEY4.png","language":"Kotlin","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Ktor Swagger-UI\n\n[![Maven Central](https://maven-badges.herokuapp.com/maven-central/io.github.smiley4/ktor-swagger-ui/badge.svg)](https://search.maven.org/artifact/io.github.smiley4/ktor-swagger-ui)\n[![Checks Passing](https://github.com/SMILEY4/ktor-swagger-ui/actions/workflows/checks.yml/badge.svg?branch=develop)](https://github.com/SMILEY4/ktor-swagger-ui/actions/workflows/checks.yml)\n\nThis library provides a Ktor plugin to document routes, generate an OpenAPI specification and serve Swagger UI.\nIt is meant to be  minimally invasive, meaning it can be plugged into existing application without requiring immediate changes to the code.\nRoutes can then be gradually enhanced with documentation.\n\n\n## Features\n\n- Minimally invasive (no immediate change to existing code required)\n- Provides Swagger UI and OpenAPI spec with minimal configuration\n- Supports most of the [OpenAPI 3.1.0 Specification](https://swagger.io/specification/)\n- Automatic [json-schema generation](https://github.com/SMILEY4/schema-kenerator) from arbitrary types/classes for bodies and parameters\n  - Supports generics, inheritance, collections, etc.\n  - (Optional) support for Jackson-annotations and swagger schema annotations \n  - Use with reflection or kotlinx-serialization\n  - Customizable schema generation\n\n\n## Documentation\n\nA wiki with a short documentation is available [here](https://github.com/SMILEY4/ktor-swagger-ui/wiki).\n\n\n## Installation\n\n```kotlin\ndependencies {\n    implementation(\"io.github.smiley4:ktor-openapi:\u003cVERSION\u003e\")\n    implementation(\"io.github.smiley4:ktor-swagger-ui:\u003cVERSION\u003e\")\n}\n```\n\n\n## Ktor compatibility\n\n- Ktor 2.x: ktor-swagger-ui up to 3.x\n- Ktor 3.x: ktor-swagger-ui starting with 4.0\n\n\n## Examples\n\nRunnable examples can be found in [ktor-swagger-ui-examples/src/main/kotlin/io/github/smiley4/ktorswaggerui/examples](https://github.com/SMILEY4/ktor-swagger-ui/tree/release/ktor-swagger-ui-examples/src/main/kotlin/io/github/smiley4/ktorswaggerui/examples).\n\n\n### Configuration\n\n```kotlin\ninstall(OpenApi) {\n  info {\n    title = \"Example API\"\n    description = \"An example api to showcase basic swagger-ui functionality.\"\n  }\n  server {\n    url = \"http://localhost:8080\"\n    description = \"Development Server\"\n  }\n}\n```\n\n```kotlin\nrouting {\n    // Create a route for the OpenAPI spec file.\n    // This route will not be included in the spec.\n    route(\"/api.json\") {\n      openApi()\n    }\n    // Create a route for swagger-ui using the openapi spec at \"/api.json\".\n    // This route will not be included in the spec.\n    route(\"/swagger\") {\n      swaggerUI(\"/api.json\")\n    }\n}\n```\n\n### Routes\n\n```kotlin\nget(\"hello\", {\n    description = \"Hello World Endpoint.\"\n    response {\n        HttpStatusCode.OK to {\n            description = \"Successful Request\"\n            body\u003cString\u003e { description = \"the response\" }\n        }\n        HttpStatusCode.InternalServerError to {\n            description = \"Something unexpected happened\"\n        }\n    }\n}) {\n    call.respondText(\"Hello World!\")\n}\n```\n\n```kotlin\npost(\"math/{operation}\", {\n    tags = listOf(\"test\")\n    description = \"Performs the given operation on the given values and returns the result\"\n    request {\n        pathParameter\u003cString\u003e(\"operation\") {\n            description = \"the math operation to perform. Either 'add' or 'sub'\"\n        }\n        body\u003cMathRequest\u003e()\n    }\n    response {\n        HttpStatusCode.OK to {\n            description = \"The operation was successful\"\n            body\u003cMathResult\u003e {\n                description = \"The result of the operation\"\n            }\n        }\n        HttpStatusCode.BadRequest to {\n            description = \"An invalid operation was provided\"\n        }\n    }\n}) {\n    val operation = call.parameters[\"operation\"]!!\n    call.receive\u003cMathRequest\u003e().let { request -\u003e\n        when (operation) {\n            \"add\" -\u003e call.respond(HttpStatusCode.OK, MathResult(request.a + request.b))\n            \"sub\" -\u003e call.respond(HttpStatusCode.OK, MathResult(request.a - request.b))\n            else -\u003e call.respond(HttpStatusCode.BadRequest, Unit)\n        }\n    }\n}\n\ndata class MathRequest(\n    val a: Int,\n    val b: Int\n)\n\ndata class MathResult(\n    val value: Int\n)\n```\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsmiley4%2Fktor-swagger-ui","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsmiley4%2Fktor-swagger-ui","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsmiley4%2Fktor-swagger-ui/lists"}