{"id":27311694,"url":"https://github.com/tabilzad/inspektor","last_synced_at":"2025-04-12T06:21:09.942Z","repository":{"id":40643070,"uuid":"500683479","full_name":"tabilzad/inspektor","owner":"tabilzad","description":"Provides Ktor Swagger support","archived":false,"fork":false,"pushed_at":"2025-03-24T02:10:08.000Z","size":555,"stargazers_count":46,"open_issues_count":5,"forks_count":9,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-03-24T03:22:25.315Z","etag":null,"topics":["android","codegen","compiler-plugin","gradle-plugin","kotlin","ktor","ktor-android","ktor-feature","ktor-server","openapi","swagger"],"latest_commit_sha":null,"homepage":"","language":"Kotlin","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tabilzad.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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-06-07T04:03:26.000Z","updated_at":"2025-03-24T02:08:55.000Z","dependencies_parsed_at":"2023-12-08T01:35:01.836Z","dependency_job_id":"cdef9d4e-921c-40c6-bf22-a8d1136f7c10","html_url":"https://github.com/tabilzad/inspektor","commit_stats":{"total_commits":108,"total_committers":3,"mean_commits":36.0,"dds":0.05555555555555558,"last_synced_commit":"3423cebdf307931b40582cdea6c0df0c65a1243d"},"previous_names":["tabilzad/inspektor"],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tabilzad%2Finspektor","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tabilzad%2Finspektor/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tabilzad%2Finspektor/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tabilzad%2Finspektor/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tabilzad","download_url":"https://codeload.github.com/tabilzad/inspektor/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248525762,"owners_count":21118749,"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":["android","codegen","compiler-plugin","gradle-plugin","kotlin","ktor","ktor-android","ktor-feature","ktor-server","openapi","swagger"],"created_at":"2025-04-12T06:21:09.172Z","updated_at":"2025-04-12T06:21:09.929Z","avatar_url":"https://github.com/tabilzad.png","language":"Kotlin","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg width=\"200\" height=\"200\" src=\"https://github.com/user-attachments/assets/da646150-24f3-43af-8b8f-188848f284a5\" /\u003e\n\u003c/p\u003e\n\n# InspeKtor\n### Open API (Swagger) generator for Ktor\n[![Test and Publish to SonarType](https://github.com/tabilzad/inspektor/actions/workflows/gradle-publish.yml/badge.svg)](https://github.com/tabilzad/inspektor/actions/workflows/gradle-publish.yml)\n\nThis plugin implements a plug and play solution for generating OpenAPI (Swagger) specification for your Ktor server on any platform with minimal effort - no need to modify your existing code, no special DSL wrappers etc.\nJust annotate your route(s) definitions with `@GenerateOpenApi` and `openapi.yaml` will be generated at build time.\n\nTake a look at the [Sample Project](https://github.com/tabilzad/ktor-inspektor-example) to get started. \n## How to apply the plugin\n\n```groovy\nplugins {\n    id(\"io.github.tabilzad.inspektor\") version \"0.7.2-alpha\"\n}\n\nswagger {\n    documentation {\n        generateRequestSchemas = true\n        hideTransientFields = true\n        hidePrivateAndInternalFields = true\n        deriveFieldRequirementFromTypeNullability = true\n        info {\n            title = \"Ktor Server Title\"\n            description = \"Ktor Server Description\"\n            version = \"1.0\"\n            contact {\n                name = \"Inspektor\"\n                url = \"https://github.com/tabilzad/inspektor\"\n            }\n        }\n    }\n\n    pluginOptions {\n        format = \"yaml\" // or json\n    }\n}\n```\n\n## Supported Features\n\n| Feature                      | isSupported | type      |\n|------------------------------|-------------|-----------|\n| Path/Endpoint definitions    | ✅           | Automatic |\n| Ktor Resources               | ✅           | Automatic |\n| Request Schemas              | ✅           | Automatic |\n| Response Schemas             | ✅           | Explicit  |\n| Endpoint/Scheme Descriptions | ✅           | Explicit  |\n| Endpoint Tagging             | ✅           | Explicit  |\n\n\n## Plugin Configuration\n\n### Documentation options\n\n| Option                         | Default Value                             | Explanation                                                                                 |\n|--------------------------------|-------------------------------------------|---------------------------------------------------------------------------------------------|\n| `info.title`                   | `\"Open API Specification\"`                | Title for the API specification that is generated                                           |\n| `info.description`             | `\"Generated using Ktor Docs Plugin\"`      | A brief description for the generated API specification                                     |\n| `info.version`                 | `\"1.0.0\"`                                 | Specifies the version for the generated API specification                                   |\n| `generateRequestSchemas`       | `true`                                    | Determines if request body schemas should \u003cbr/\u003ebe automatically resolved and included       |\n| `hideTransientFields`          | `true`                                    | Controls whether fields marked with `@Transient` \u003cbr/\u003e are omitted in schema outputs        |\n| `hidePrivateAndInternalFields` | `true`                                    | Opts to exclude fields with `private` or `internal` modifiers from schema outputs           |\n| `deriveFieldRequirementFromTypeNullability` | `true`                       | Automatically derive object fields' requirement from its type nullability                   |\n| `servers`                      | []                                        | List of server URLs to be included in the spec  (ex: `listOf(\"http://localhost:8080\")`      |\n\n### Plugin options\n| Option                         | Default Value                                | Explanation                                                                                 |\n|--------------------------------|----------------------------------------------|---------------------------------------------------------------------------------------------|\n| `enabled`                      | `true`                                       | Enable/Disables the plugin                                                                  |\n| `saveInBuild`                  | `true`                                       | Decides if the generated specification file should \u003cbr/\u003e be saved in the `build/` directory |\n| `format`                       | `yaml`                                       | The chosen format for the OpenAPI specification \u003cbr/\u003e(options: json/yaml)                   |\n| `filePath`                     | `$modulePath/build/resources/main/openapi/`  | The designated absolute path for saving \u003cbr/\u003e the generated specification file              |\n\n## How to use the plugin\n\n### Generating endpoint specifications\n\nAnnotate the specific route definitions you want the OpenAPI specification to be generated for.\n\n```kotlin\n\n@GenerateOpenApi\nfun Route.ordersRouting() {\n    route(\"/v1\") {\n        post(\"/order1\") {\n            /*...*/\n        }\n    }\n}\n\n```\n\nYou could also annotate the entire `Application` module with multiple/nested route definitions. The plugin will\nrecursively visit each `Route`. extension and generate its documentation.\n\n```kotlin\n\n@GenerateOpenApi\nfun Application.ordersModule() {\n    routing {\n        routeOne()\n        routeTwo()\n    }\n}\n\nfun Route.routeOne() {\n    route(\"/v1\") { /*...*/ }\n}\n\nfun Route.routeTwo() {\n    route(\"/v2\") { /*...*/ }\n    routeThree()\n}\n\n```\n\n### Endpoint and field descriptions\n\nDescribe endpoints or schema fields.\n\n```kotlin\ndata class RequestSample(\n    @KtorFieldDescription(\"this is a string\")\n    val string: String,\n    val int: Int,\n    val double: Double,\n    @KtorFieldDescription(summary = \"this is instant\", explicitType = \"string\", format = \"date-time\")\n    val date: Instant\n)\n\n@GenerateOpenApi\nfun Route.ordersRouting() {\n    route(\"/v1\") {\n        @KtorDescription(\n            summary = \"Create Order\",\n            description = \"This endpoint will create an order\",\n        )\n        post(\"/create\") {\n            call.receive\u003cRequestSample\u003e()\n        }\n\n        route(\"/orders\") {\n            @KtorDescription(\n                summary = \"All Orders\",\n                description = \"This endpoint will return a list of all orders\"\n            )\n            get { /*...*/ }\n        }\n    }\n}\n```\n\n### Responses\nDefining response schemas and their corresponding HTTP status codes are done via `@KtorResponds` annotation on an endpoint. \n`kotlin.Nothing` is treated specially and will result in empty response body.\n\n```kotlin\n@GenerateOpenApi\nfun Route.ordersRouting() {\n    route(\"/v1\") {\n        @KtorResponds(\n               [\n                   ResponseEntry(\"200\", Order::class, description = \"Created order\"),\n                   ResponseEntry(\"204\", Nothing::class),\n                   ResponseEntry(\"400\", ErrorResponseSample::class, description = \"Invalid order payload\")\n               ]\n        )\n        post(\"/create\") { /*...*/ }\n        @KtorResponds([ResponseEntry(\"200\", Order::class, isCollection=true, description = \"All orders\")])\n        get(\"/orders\") { /*...*/ }\n    }\n}\n```\n\n### Tagging\n\nUsing tags enables the categorization of individual endpoints into designated groups. \nTags specified at the parent route will propogate down to all endpoints contained within it.\n\n```kotlin\n@Tag([\"Orders\"])\nfun Route.ordersRouting() {\n    route(\"/v1\") {\n        post(\"/create\") { /*...*/ }\n        get(\"/orders\") { /*...*/ }\n    }\n    route(\"/v2\") {\n        post(\"/create\") { /*...*/ }\n        get(\"/orders\") { /*...*/ }\n    }\n}\n```\nOn the other hand, if the tags are specified with `@KtorDescription` or `@Tag` annotation on an endpoint, they are associated exclusively with that particular endpoint.\n\n```kotlin\n@GenerateOpenApi\nfun Route.ordersRouting() {\n    route(\"/v1\") {\n        @KtorDescription(tags = [\"Order Operations\"])\n        post(\"/order\") { /*...*/ }\n        @Tag([\"Cart Operations\"])\n        get(\"/cart\") { /*...*/ }\n    }\n}\n```\n\n## Planned Features\n\n* Automatic Response resolution\n* Support for polymorphic types with discriminators \n* Option for an automatic tag resolution from module/route function declaration\n* Tag descriptions\n\n## Sample Specification\n\n![sample](https://github.com/tabilzad/inspektor/assets/16094286/6d0b0a6a-5925-4f52-ad23-11b1c44b43a1)\n\n\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftabilzad%2Finspektor","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftabilzad%2Finspektor","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftabilzad%2Finspektor/lists"}