{"id":18336554,"url":"https://github.com/kumuluz/kumuluzee-openapi-mp","last_synced_at":"2025-07-06T14:39:14.179Z","repository":{"id":53144586,"uuid":"172050864","full_name":"kumuluz/kumuluzee-openapi-mp","owner":"kumuluz","description":"KumuluzEE OpenAPI MicroProfile project provides powerful tools to incorporate the OpenAPI 3 specification to your microservices in a standardized way.","archived":false,"fork":false,"pushed_at":"2023-11-29T10:03:20.000Z","size":138,"stargazers_count":2,"open_issues_count":2,"forks_count":1,"subscribers_count":13,"default_branch":"master","last_synced_at":"2025-03-21T17:23:39.005Z","etag":null,"topics":["cloud-native","jakartaee","java","javaee","kumuluz","kumuluzee","microprofile","microservices","openapi","openapi3","rest"],"latest_commit_sha":null,"homepage":"https://ee.kumuluz.com/","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kumuluz.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","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}},"created_at":"2019-02-22T10:59:42.000Z","updated_at":"2022-06-07T13:02:06.000Z","dependencies_parsed_at":"2024-01-08T12:17:44.586Z","dependency_job_id":null,"html_url":"https://github.com/kumuluz/kumuluzee-openapi-mp","commit_stats":{"total_commits":51,"total_committers":6,"mean_commits":8.5,"dds":0.5098039215686274,"last_synced_commit":"2f4d6046a4246c59611d1b712b3f13f4728bf904"},"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kumuluz%2Fkumuluzee-openapi-mp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kumuluz%2Fkumuluzee-openapi-mp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kumuluz%2Fkumuluzee-openapi-mp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kumuluz%2Fkumuluzee-openapi-mp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kumuluz","download_url":"https://codeload.github.com/kumuluz/kumuluzee-openapi-mp/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247435041,"owners_count":20938530,"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":["cloud-native","jakartaee","java","javaee","kumuluz","kumuluzee","microprofile","microservices","openapi","openapi3","rest"],"created_at":"2024-11-05T20:08:15.721Z","updated_at":"2025-04-06T04:35:36.954Z","avatar_url":"https://github.com/kumuluz.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# KumuluzEE OpenAPI MicroProfile\n[![KumuluzEE CI](https://github.com/kumuluz/kumuluzee-openapi-mp/actions/workflows/kumuluzee-ci.yml/badge.svg)](https://github.com/kumuluz/kumuluzee-openapi-mp/actions/workflows/kumuluzee-ci.yml)\n\n\u003e KumuluzEE OpenAPI MicroProfile project provides powerful tools to incorporate the OpenAPI 3 specification to your\nmicroservices in a standardized way.\n\nKumuluzEE OpenAPI MicroProfile project allows you to document microservice APIs using OpenAPI v3 compliant annotations.\nProject will automatically hook-up servlet that will serve your API specifications on endpoint `/openapi`.\nThe project implements the MicroProfile OpenAPI specification.\n \nMore details: \n\n- [OpenAPI v3 Specification](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md)\n- [MicroProfile OpenAPI specification](https://github.com/eclipse/microprofile-open-api/releases)\n\n## Usage\n\nYou can enable KumuluzEE OpenAPI MicroProfile support by adding the following dependency:\n```xml\n\u003cdependency\u003e\n    \u003cgroupId\u003ecom.kumuluz.ee.openapi\u003c/groupId\u003e\n    \u003cartifactId\u003ekumuluzee-openapi-mp\u003c/artifactId\u003e\n    \u003cversion\u003e${kumuluzee-openapi-mp.version}\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\n## OpenAPI configuration\n\nWhen kumuluzee-openapi-mp dependency is included in the project, you can start documenting your REST API using\nMicroProfile OpenAPI annotations.\n\n### Documenting application class\n\n```java\n@SecurityScheme(securitySchemeName = \"openid-connect\", type = SecuritySchemeType.OPENIDCONNECT,\n        openIdConnectUrl = \"http://auth-server-url/.well-known/openid-configuration\")\n@ApplicationPath(\"v2\")\n@OpenAPIDefinition(info = @Info(title = \"CustomerApi\", version = \"v2.0.0\", contact = @Contact(), license = @License(name=\"something\")), servers = @Server(url = \"http://localhost:8080\"), security\n        = @SecurityRequirement(name = \"openid-connect\"))\npublic class CustomerApplication extends Application {\n}\n```\n\n### Documenting resource class and operations\n\n```java\n@Path(\"customers\")\n@Consumes(MediaType.APPLICATION_JSON)\n@Produces(MediaType.APPLICATION_JSON)\npublic class CustomerResource {\n\n    @GET\n    @Operation(summary = \"Get customers details\", description = \"Returns customer details.\")\n    @APIResponses({\n            @APIResponse(description = \"Customer details\", responseCode = \"200\", content = @Content(schema = @Schema(implementation =\n                    Customer.class)))\n    })\n    @Path(\"{customerId}\")\n    public Response getCustomer(@PathParam(\"customerId\") String customerId) {\n        // ...\n    }\n\n}\n```\n\n## Accessing API specification\n\nBuild and run project using:\n\n```bash\nmvn clean package\njava -jar target/${project.build.finalName}.jar\n```\n\nAfter startup API specification will be available at:\n\n**http://\u003c-hostname-\u003e:\u003c-port-\u003e/\u003c-optional-context-path-\u003e/openapi**\n\nExample:\n\nhttp://localhost:8080/openapi\n\nServing OpenAPI specification can be disabled by setting property **kumuluzee.openapi-mp.enabled** to false. By default\nserving API spec is enabled.\n\n## Configuration\n\nThe KumuluzEE OpenAPI MicroProfile extension can be configured with the standard KumuluzEE configuration mechanism. For\nexample with the _config.yml_ file:\n\n```yaml\nkumuluzee:\n  openapi-mp:\n    enabled: true\n    servlet:\n      mapping: /openapi-custom-mapping\n    scan:\n      packages: com.kumuluz.ee.samples.openapi\n    servers: https://example-api.com,https://my-proxy.com\n```\n\nSome interesting configuration properties are:\n\n- `kumuluzee.openapi-mp.enabled` - If set to `false` disables the extension (and OpenAPI servlet). Default value: `true`\n- `kumuluzee.openapi-mp.servlet.mapping` - The endpoint at which the OpenAPI specification is available. Appended to optional server context path. Default value: `/openapi`\n- `kumuluzee.openapi-mp.scan.packages` - Comma separated list of packages which are scanned for the OpenAPI annotations.\n  By default, all packages are scanned.\n\nFull list of configuration properties can be found in\n[MicroProfile OpenAPI specification](https://github.com/eclipse/microprofile-open-api/releases).\n\n## Scanning\n\nBy default KumuluzEE OpenAPI MP uses optimized scanning in order to reduce startup times. This means that only the main\napplication JAR will be scanned (main artifact). In order to scan additional artifacts you need to specify them using\nthe [scan-libraries mechanism](https://github.com/kumuluz/kumuluzee/pull/123). You need to include all dependencies\nwhich contain JAX-RS application and resources as well as dependencies containing models returned from JAX-RS resources.\nIf all your models and resources are in the main artifact you don't need to include anything. For example to include\n_my-models_ artifact use the following configuration:\n\n```yaml\nkumuluzee:\n  dev:\n    scan-libraries:\n      - my-models\n```\n\nIf you are unsure if your configuration is correct you can try to disable optimized scanning by using the following\nconfiguration:\n\n```yaml\nkumuluzee:\n  openapi-mp:\n    scanning:\n      optimize: false\n```\n\nYou can also enable scan debugging by setting the following key to `true`: `kumuluzee.openapi-mp.scanning.debug`. This\nwill output a verbose log of scanning configuration and progress.\n\n## Adding Swagger UI\n\nTo serve API specification in visual form and to allow API consumers to interact with API resources you can add\nSwagger UI by including the __kumuluzee-swagger-ui__ dependency:\n\n```xml\n\u003cdependency\u003e\n    \u003cgroupId\u003ecom.kumuluz.ee.openapi\u003c/groupId\u003e\n    \u003cartifactId\u003ekumuluzee-openapi-mp-ui\u003c/artifactId\u003e\n    \u003cversion\u003e${kumuluzee-openapi-mp.version}\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\nSwagger UI is automatically enabled and is available at __/api-specs/ui__. In order to disable Swagger UI you can set\nthe configuration key `kumuluzee.openapi-mp.ui.enabled` to `false`. You can also remap the Swagger UI to another\nlocation by setting the `kumuluzee.openapi-mp.ui.mapping` key (default value: `/api-specs/ui`). Path is appended to optional server context path.\n\nSwagger UI needs to know where the OpenAPI specification is served from. It tries to define it from the following\nsources:\n\n1. Static: `\u003cprotocol\u003e://localhost:\u003cport\u003e` (useful when nothing is defined, lowest priority)\n1. From the `servers` parameter in `@OpenAPIDefinition` annotation (useful when OpenAPI specification is available from\n   the same hostname as Swagger UI)\n1. Configuration property: `kumuluzee.server.base-url` (useful for overriding above values)\n1. Configuration property: `kumuluzee.openapi-mp.ui.specification-server` (same as above but in a namespace specific to\n   this extension)\n   \n## Swagger UI server auto configuration\n\nServer auto configuration allows for dynamic resolution of parameters like `kumuluzee.openapi-mp.ui.specification-server` \ninstead of need to set it. This is done by retrieving necessary information from request during runtime and based on that \nsetting correct redirect. It is especially useful when service is being deployed in multiple environments.\nThis feature also updates list of servers in Swagger UI and reorder them, so it will be first one.\nIt is also possible to resolve correct redirect when service is behind for example Ingres (Ingress must have enabled feature which \nforwards original URL).\n\nBy default, this feature is disabled for backward compatibility. To enable it set `kumuluzee.openapi-mp.ui.auto-config.enabled`\nto `true`. To enable (Ingress) URI check set `kumuluzee.openapi-mp.ui.auto-config.original-uri-check` to `true`.\n\nDefault settings for server auto configuration:\n```yaml\nkumuluzee:\n  openapi-mp:\n    ui:\n      server-auto-config:\n        enabled: false\n        original-uri-check: false\n```\n\n\u003e **note:** localhost server with same port is added only once (if not already specified in @OpenAPIDefinition) and in case in which \n\u003e is used localhost address in different format (for example http://127.0.0.1:8080 instead of http://localhost:8080), \n\u003eno new server will be added to list and because of this Swagger UI will be unable to do API calls (this is due to issue with cors) \n\n## OpenAPI Maven Plugin\n\nMaven plugin can be used to generate OpenAPI schema when building the application. To use it add the following to\npom.xml:\n\n```xml\n\u003cplugin\u003e\n    \u003cartifactId\u003ekumuluzee-openapi-mp-maven-plugin\u003c/artifactId\u003e\n    \u003cgroupId\u003ecom.kumuluz.ee.openapi\u003c/groupId\u003e\n    \u003cversion\u003e${kumuluzee-openapi-mp.version}\u003c/version\u003e\n    \u003cexecutions\u003e\n        \u003cexecution\u003e\n            \u003cgoals\u003e\n                \u003cgoal\u003egenerate\u003c/goal\u003e\n            \u003c/goals\u003e\n        \u003c/execution\u003e\n    \u003c/executions\u003e\n\u003c/plugin\u003e\n```\n\nBy default, the schema is generated in `target/generated/` directory in JSON and YAML formats.\n\nIf the schema is defined across multiple artefacts you must define the `\u003cscanLibraries\u003e\u003c/scanLibraries\u003e` configuration\nproperty with comma-separated list of dependencies in the same format as described in the [Scanning](#scanning) section\nabove.\n\nMaven plugin uses SmallRye implementation in order to generate the schema. For more configuration options see the\nfollowing document: https://github.com/smallrye/smallrye-open-api/tree/master/tools/maven-plugin#configuration-options\n\n## Changelog\n\nRecent changes can be viewed on Github on the [Releases Page](https://github.com/kumuluz/kumuluzee-openapi-mp/releases)\n\n\n## Contribute\n\nSee the [contributing docs](https://github.com/kumuluz/kumuluzee-openapi-mp/blob/master/CONTRIBUTING.md)\n\nWhen submitting an issue, please follow the \n[guidelines](https://github.com/kumuluz/kumuluzee-openapi-mp/blob/master/CONTRIBUTING.md#bugs).\n\nWhen submitting a bugfix, write a test that exposes the bug and fails before applying your fix. Submit the test \nalongside the fix.\n\nWhen submitting a new feature, add tests that cover the feature.\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkumuluz%2Fkumuluzee-openapi-mp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkumuluz%2Fkumuluzee-openapi-mp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkumuluz%2Fkumuluzee-openapi-mp/lists"}