{"id":18300384,"url":"https://github.com/taymyr/lagom-openapi","last_synced_at":"2025-10-06T04:25:05.571Z","repository":{"id":49643304,"uuid":"148335201","full_name":"taymyr/lagom-openapi","owner":"taymyr","description":"OpenAPI/Swagger module for Lagom","archived":false,"fork":false,"pushed_at":"2021-11-19T06:52:10.000Z","size":345,"stargazers_count":38,"open_issues_count":4,"forks_count":7,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-07-26T11:05:28.917Z","etag":null,"topics":["lagom","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":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/taymyr.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}},"created_at":"2018-09-11T15:01:02.000Z","updated_at":"2025-03-31T14:50:02.000Z","dependencies_parsed_at":"2022-09-18T12:30:26.836Z","dependency_job_id":null,"html_url":"https://github.com/taymyr/lagom-openapi","commit_stats":null,"previous_names":["taymyr/openapi-java"],"tags_count":9,"template":false,"template_full_name":null,"purl":"pkg:github/taymyr/lagom-openapi","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/taymyr%2Flagom-openapi","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/taymyr%2Flagom-openapi/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/taymyr%2Flagom-openapi/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/taymyr%2Flagom-openapi/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/taymyr","download_url":"https://codeload.github.com/taymyr/lagom-openapi/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/taymyr%2Flagom-openapi/sbom","scorecard":{"id":869969,"data":{"date":"2025-08-11","repo":{"name":"github.com/taymyr/lagom-openapi","commit":"0c8c96580f5231f52c4ca1b2a38d78c168d18d9b"},"scorecard":{"version":"v5.2.1-40-gf6ed084d","commit":"f6ed084d17c9236477efd66e5b258b9d4cc7b389"},"score":3.3,"checks":[{"name":"Packaging","score":-1,"reason":"packaging workflow not detected","details":["Warn: no GitHub/GitLab publishing workflow detected."],"documentation":{"short":"Determines if the project is published as a package that others can easily download, install, easily update, and uninstall.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#packaging"}},{"name":"Token-Permissions","score":0,"reason":"detected GitHub workflow tokens with excessive permissions","details":["Warn: no topLevel permission defined: .github/workflows/release-drafter.yml:1","Info: no jobLevel write permissions found"],"documentation":{"short":"Determines if the project's workflows follow the principle of least privilege.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#token-permissions"}},{"name":"Dangerous-Workflow","score":10,"reason":"no dangerous workflow patterns detected","details":null,"documentation":{"short":"Determines if the project's GitHub Action workflows avoid dangerous patterns.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#dangerous-workflow"}},{"name":"Code-Review","score":0,"reason":"Found 2/30 approved changesets -- score normalized to 0","details":null,"documentation":{"short":"Determines if the project requires human code review before pull requests (aka merge requests) are merged.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#code-review"}},{"name":"Maintained","score":0,"reason":"0 commit(s) and 0 issue activity found in the last 90 days -- score normalized to 0","details":null,"documentation":{"short":"Determines if the project is \"actively maintained\".","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#maintained"}},{"name":"Binary-Artifacts","score":9,"reason":"binaries present in source code","details":["Warn: binary detected: gradle/wrapper/gradle-wrapper.jar:1"],"documentation":{"short":"Determines if the project has generated executable (binary) artifacts in the source repository.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#binary-artifacts"}},{"name":"Pinned-Dependencies","score":0,"reason":"dependency not pinned by hash detected -- score normalized to 0","details":["Warn: third-party GitHubAction not pinned by hash: .github/workflows/release-drafter.yml:14: update your workflow using https://app.stepsecurity.io/secureworkflow/taymyr/lagom-openapi/release-drafter.yml/master?enable=pin","Info:   0 out of   1 third-party GitHubAction dependencies pinned"],"documentation":{"short":"Determines if the project has declared and pinned the dependencies of its build process.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#pinned-dependencies"}},{"name":"CII-Best-Practices","score":0,"reason":"no effort to earn an OpenSSF best practices badge detected","details":null,"documentation":{"short":"Determines if the project has an OpenSSF (formerly CII) Best Practices Badge.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#cii-best-practices"}},{"name":"Vulnerabilities","score":10,"reason":"0 existing vulnerabilities detected","details":null,"documentation":{"short":"Determines if the project has open, known unfixed vulnerabilities.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#vulnerabilities"}},{"name":"Fuzzing","score":0,"reason":"project is not fuzzed","details":["Warn: no fuzzer integrations found"],"documentation":{"short":"Determines if the project uses fuzzing.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#fuzzing"}},{"name":"License","score":10,"reason":"license file detected","details":["Info: project has a license file: LICENSE:0","Info: FSF or OSI recognized license: Apache License 2.0: LICENSE:0"],"documentation":{"short":"Determines if the project has defined a license.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#license"}},{"name":"Signed-Releases","score":-1,"reason":"no releases found","details":null,"documentation":{"short":"Determines if the project cryptographically signs release artifacts.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#signed-releases"}},{"name":"Security-Policy","score":0,"reason":"security policy file not detected","details":["Warn: no security policy file detected","Warn: no security file to analyze","Warn: no security file to analyze","Warn: no security file to analyze"],"documentation":{"short":"Determines if the project has published a security policy.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#security-policy"}},{"name":"Branch-Protection","score":0,"reason":"branch protection not enabled on development/release branches","details":["Warn: branch protection not enabled for branch 'master'"],"documentation":{"short":"Determines if the default and release branches are protected with GitHub's branch protection settings.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#branch-protection"}},{"name":"SAST","score":0,"reason":"SAST tool is not run on all commits -- score normalized to 0","details":["Warn: 0 commits out of 20 are checked with a SAST tool"],"documentation":{"short":"Determines if the project uses static code analysis.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#sast"}}]},"last_synced_at":"2025-08-24T03:51:30.638Z","repository_id":49643304,"created_at":"2025-08-24T03:51:30.638Z","updated_at":"2025-08-24T03:51:30.638Z"},"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278557572,"owners_count":26006349,"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","status":"online","status_checked_at":"2025-10-06T02:00:05.630Z","response_time":65,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["lagom","openapi","swagger"],"created_at":"2024-11-05T15:12:11.289Z","updated_at":"2025-10-06T04:25:05.552Z","avatar_url":"https://github.com/taymyr.png","language":"Kotlin","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Gitter](https://img.shields.io/badge/chat-gitter-purple.svg)](https://gitter.im/taymyr/taymyr)\n[![Gitter_RU](https://img.shields.io/badge/chat-russian%20channel-purple.svg)](https://gitter.im/taymyr/taymyr_ru)\n[![Build Status](https://travis-ci.org/taymyr/lagom-openapi.svg?branch=master)](https://travis-ci.org/taymyr/lagom-openapi)\n[![codecov](https://codecov.io/gh/taymyr/lagom-openapi/branch/master/graph/badge.svg)](https://codecov.io/gh/taymyr/lagom-openapi)\n[![Maven](https://img.shields.io/maven-central/v/org.taymyr.lagom/lagom-openapi-core_2.12.svg)](https://search.maven.org/search?q=a:lagom-openapi-*2.12%20AND%20g:org.taymyr.lagom)\n\n# [OpenAPI/Swagger](https://swagger.io/specification/) module for [Lagom](https://www.lagomframework.com)\n\nThe Lagom OpenAPI module has two common features:\n \n* Generation OpenAPI 3.X specification for the Lagom service by annotations. (How to use with [Scala DSL](#11-generate-scala-dsl)/[Java DSL](#12-generate-java-dsl))\n* Publishing static OpenAPI 3.X/Swagger 2.X specification from the classpath. (How to use with [Scala DSL](#21-static-scala-dsl)/[Java DSL](#22-static-java-dsl))\n\nAlso, you can see how to generate OpenAPI Specification for Lagom service on demo projects ([Java/Maven example](https://github.com/taymyr/lagom-samples/blob/master/openapi/java/README.md), [Scala/Sbt example](https://github.com/taymyr/lagom-samples/blob/master/openapi/scala/README.md)).\n\n## Versions compatibility\n\n| Lagom OpenAPI | OpenAPI / Swagger | Lagom 1.4          | Lagom 1.5          | Lagom 1.6          | Scala 2.11         | Scala 2.12         | Scala 2.13         |\n|:-------------:|:-----------------:|:------------------:|:------------------:|:------------------:|:------------------:|:------------------:|:------------------:|\n| 1.+           | 2.0.7+            | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: |\n\n# How to use\n\n## 1.1 Generate (Scala DSL)\n\n### 1.1.1 Dependencies\n\n[*Only for Lagom 1.4.X*] You need to add next dependencies to the _API_ module of Lagom service:\n\n```scala\nval swaggerAnnotations = \"io.swagger.core.v3\" % \"swagger-annotations\" % \"2.0.7\"\nval lagomOpenapiApi = \"org.taymyr.lagom\" %% \"lagom-openapi-scala-api\" % lagomOpenapiVersion\n\nlazy val `lagom-service-api` = (project in file(\"api\"))\n  .settings(\n    libraryDependencies ++= Seq(\n      ...\n      swaggerAnnotations,\n      lagomOpenapiApi\n    )\n  )\n```\n\nand next dependencies to the _Implementation_ module of Lagom service:\n\n```scala\nval lagomOpenapiImpl = \"org.taymyr.lagom\" %% \"lagom-openapi-scala-impl\" % lagomOpenapiVersion\n\nlazy val `lagom-service-impl` = (project in file(\"impl\"))\n  .enablePlugins(LagomScala)\n  .settings(\n    libraryDependencies ++= Seq(\n      ...\n      lagomOpenapiImpl\n    )\n  )\n```\n\n### 1.1.2 Service Descriptor\n\nNecessarily add `OpenAPIDefinition` annotation to Lagom service descriptor and extend (*only for Lagom 1.4.X*) descriptor by `OpenAPIService` trait:\n\n```scala\n@OpenAPIDefinition(\n  info = new Info(\n    version = \"1.0.0\",\n    title = \"My Service\"\n  ),\n  ...\n)\ntrait MyService extends OpenAPIService with Service {\n  ...\n}\n```\n\nThen you can use OpenAPI annotations for the methods of your service. For more information about annotations see the [official wiki](https://github.com/swagger-api/swagger-core/wiki/Swagger-2.X---Annotations).\n\n```scala\n@Operation(...)\n@Tag(...)\n...\ndef method: ServiceCall[_, _]\n```\n\n[*Only for Lagom 1.4.X*]  In conclusion, you must add the route for OpenAPI specification. You can do that with helper function `withOpenAPI` (default route is `/_\u003cservice_name\u003e/openapi`)\n\n```scala\noverride def descriptor: Descriptor = named(\"service\")\n    .withOpenAPI()\n    ...\n```\n\nor use a custom route\n\n```scala\noverride def descriptor: Descriptor = named(\"service\")\n    .withCalls(\n      ...\n      pathCall(\"/custom/route\", openapi)\n    )\n```\n\n### 1.1.3 Service implementation [Lagom 1.4.X]\n\nExtend your service by the `OpenAPIServiceImpl` trait:\n\n```scala\nclass MyServiceImpl(override val config: Config)\n    extends MyService\n    with OpenAPIServiceImpl {\n      ...\n}\n```\n\n### 1.1.4 Additional router [Lagom 1.5.X+]\n\nAdd [additional router](https://www.lagomframework.com/documentation/current/scala/AdditionalRouters.html#Additional-Routers) for your service\n\n```scala\noverride lazy val lagomServer = {\n  val service = wire[PetsServiceImpl]\n  serverFor[PetsService](service)\n    .additionalRouter(wire[OpenAPIRouter].router(service))\n}\n```\n\n### 1.1.5 Conclusion\n\nNow you can run service and get OpenAPI specification by a sent HTTP request to the registered route. For example by default:\n\n```bash\ncurl \"http://localhost:9000/_\u003cservice_name\u003e/openapi[?format=json|yaml]\"\n``` \n\n## 1.2 Generate (Java DSL)\n\n### 1.2.1 Dependencies\n\n[*Only for Lagom 1.4.X*] You need to add next dependencies to the _API_ module of Lagom service:\n\n**Maven**\n\n```xml\n\u003cdependencies\u003e\n    \u003cdependency\u003e\n        \u003cgroupId\u003eorg.taymyr.lagom\u003c/groupId\u003e\n        \u003cartifactId\u003elagom-openapi-java-api_${scala.binary.version}\u003c/artifactId\u003e\n        \u003cversion\u003e${lagom.openapi.version}\u003c/version\u003e\n    \u003c/dependency\u003e\n    \u003cdependency\u003e\n        \u003cgroupId\u003eio.swagger.core.v3\u003c/groupId\u003e\n        \u003cartifactId\u003eswagger-annotations\u003c/artifactId\u003e\n        \u003cversion\u003e2.0.7\u003c/version\u003e\n    \u003c/dependency\u003e\n\u003c/dependencies\u003e\n```\n\n**Sbt**\n\n```scala\nval swaggerAnnotations = \"io.swagger.core.v3\" % \"swagger-annotations\" % \"2.0.7\"\nval lagomOpenapiApi = \"org.taymyr.lagom\" %% \"lagom-openapi-java-api\" % lagomOpenapiVersion\n\nlazy val `lagom-service-api` = (project in file(\"api\"))\n  .settings(\n    libraryDependencies ++= Seq(\n      ...\n      swaggerAnnotations,\n      lagomOpenapiApi\n    )\n  )\n```\n\nand next dependencies to the _Implementation_ module of Lagom service:\n\n**Maven**\n\n```xml\n\u003cdependencies\u003e\n    \u003cdependency\u003e\n        \u003cgroupId\u003eorg.taymyr.lagom\u003c/groupId\u003e\n        \u003cartifactId\u003elagom-openapi-java-impl_${scala.binary.version}\u003c/artifactId\u003e\n        \u003cversion\u003e${lagom.openapi.version}\u003c/version\u003e\n    \u003c/dependency\u003e\n\u003c/dependencies\u003e\n```\n\n**Sbt**\n\n```scala\nval lagomOpenapiImpl = \"org.taymyr.lagom\" %% \"lagom-openapi-java-impl\" % lagomOpenapiVersion\n\nlazy val `lagom-service-impl` = (project in file(\"impl\"))\n  .enablePlugins(LagomScala)\n  .settings(\n    libraryDependencies ++= Seq(\n      ...\n      lagomOpenapiImpl\n    )\n  )\n```\n\n### 1.2.2 Service Descriptor\n\nNecessarily add `OpenAPIDefinition` annotation to Lagom service descriptor and extend (*only for Lagom 1.4.X*) descriptor by `OpenAPIService` interface:\n\n```java\n@OpenAPIDefinition(\n  info = @Info(\n    version = \"1.0.0\",\n    title = \"My Service\"\n  ),\n  ...\n)\npublic interface MyService extends OpenAPIService {\n  ...\n}\n```\n\nThen you can use OpenAPI annotations for the methods of your service. For more information about annotations see the [official wiki](https://github.com/swagger-api/swagger-core/wiki/Swagger-2.X---Annotations).\n\n```java\n@Operation(...)\n@Tag(...)\n...\nServiceCall\u003c_, _\u003e method();\n```\n\n[*Only for Lagom 1.4.X*]  In conclusion, you must add the route for OpenAPI specification. You can do that with helper function `withOpenAPI` (default route is `/_\u003cservice_name\u003e/openapi`)\n\n```java\n@Override\ndefault Descriptor descriptor() {\n  return withOpenAPI(\n    named(\"service\")\n      ...\n  );\n}\n```\n\nor use a custom route\n\n```java\n@Override\ndefault Descriptor descriptor() {\n  return named(\"service\")\n    .withCalls(\n      ...\n      pathCall(\"/custom/route\", this::openapi)\n    );\n}\n```\n\n### 1.2.3 Service implementation [Lagom 1.4.X]\n\n[*Only for Lagom 1.4.X*] Extend your service by the abstract `AbstractOpenAPIService`:\n\n```java\npublic class MyServiceImpl extends AbstractOpenAPIService implements MyService {\n      ...\n}\n```\n\n### 1.2.4 Additional router [Lagom 1.5.X+]\n\nAdd [additional router](https://www.lagomframework.com/documentation/current/java/AdditionalRouters.html#Additional-Routers) for your service\n\n```java\n@Override\nprotected void configure() {\n    OpenAPIRouter openAPIRouter = new OpenAPIRouter(\n        getProvider(RoutingDsl.class),\n        getProvider(MyServiceImpl.class),\n        getProvider(Config.class)\n    );\n    bindService(MyService.class, MyServiceImpl.class, additionalRouter(openAPIRouter));\n}\n```\n\n### 1.2.5 Conclusion\n\nNow you can run service and get OpenAPI specification by a sent HTTP request to the registered route. For example by default:\n\n```bash\ncurl \"http://localhost:9000/_\u003cservice_name\u003e/openapi[?format=json|yaml]\"\n``` \n\n## 2.1 Static (Scala DSL)\n\n### 2.1.1 Dependencies\n\n[*Only for Lagom 1.4.X*] You need to add next dependencies to the _API_ module of Lagom service:\n\n```scala\nval lagomOpenapiApi = \"org.taymyr.lagom\" %% \"lagom-openapi-scala-api\" % lagomOpenapiVersion\n\nlazy val `lagom-service-api` = (project in file(\"api\"))\n  .settings(\n    libraryDependencies ++= Seq(\n      ...\n      lagomOpenapiApi\n    )\n  )\n```\n\nand next dependencies to the _Implementation_ module of Lagom service:\n\n```scala\nval lagomOpenapiImpl = \"org.taymyr.lagom\" %% \"lagom-openapi-scala-impl\" % lagomOpenapiVersion\n\nlazy val `lagom-service-impl` = (project in file(\"impl\"))\n  .enablePlugins(LagomScala)\n  .settings(\n    libraryDependencies ++= Seq(\n      ...\n      lagomOpenapiImpl\n    )\n  )\n```\n\n### 2.1.2 Service Descriptor\n\n[*Only for Lagom 1.4.X*] Extend Lagom service descriptor by `OpenAPIService` trait:\n\n```scala\ntrait MyService extends OpenAPIService with Service {\n  ...\n}\n```\n\nAdd OpenAPI/Swagger specification file to classpath (typically `src/main/resources` folder) of _API_ module. By default, the file should be named `\u003cservice_name\u003e.[yml|yaml|json]`.\n\n```yaml\nopenapi: 3.0.0\ninfo:\n  title: My Service\n  version: 1.0.0\npaths:\n  ...\n```\n\nAlso, you can change filename using `openapi.file` configuration in `application.conf`.\n\n```HOCON\nopenapi.file = foobar.yml\n```\n\n[*Only for Lagom 1.4.X*] In conclusion, you must add the route for OpenAPI specification. You can do that with helper function `withOpenAPI` (default route is `/_\u003cservice_name\u003e/openapi`)\n\n```scala\noverride def descriptor: Descriptor = withOpenAPI(\n  named(\"service\")\n    ...\n)\n```\n\nor use a custom route\n\n```scala\noverride def descriptor: Descriptor = named(\"service\")\n    .withCalls(\n      ...\n      pathCall(\"/custom/route?format\", openapi)\n    )\n```\n\n### 2.1.3 Service implementation [Lagom 1.4.X]\n\n[*Only for Lagom 1.4.X*] Extend your service by the `OpenAPIServiceImpl` trait:\n\n```scala\nclass MyServiceImpl(override val config: Config)\n    extends MyService\n    with OpenAPIServiceImpl {\n      ...\n}\n```\n\n### 2.1.4 Additional router [Lagom 1.5.X+]\n\nAdd [additional router](https://www.lagomframework.com/documentation/current/scala/AdditionalRouters.html#Additional-Routers) for your service\n\n```scala\noverride lazy val lagomServer = {\n  val service = wire[PetsServiceImpl]\n  serverFor[PetsService](service)\n    .additionalRouter(wire[OpenAPIRouter].router(service))\n}\n```\n\n### 2.1.5 Conclusion\n\nNow you can run service and get OpenAPI specification by a sent HTTP request to the registered route. For example by default:\n\n```bash\ncurl \"http://localhost:9000/_\u003cservice_name\u003e/openapi[?format=json|yaml]\"\n``` \n\n\n## 2.2 Static (Java DSL)\n\n### 2.2.1 Dependencies\n\n[*Only for Lagom 1.4.X*] You need to add next dependencies to the _API_ module of Lagom service:\n\n**Maven**\n\n```xml\n\u003cdependencies\u003e\n    \u003cdependency\u003e\n        \u003cgroupId\u003eorg.taymyr.lagom\u003c/groupId\u003e\n        \u003cartifactId\u003elagom-openapi-java-api_${scala.binary.version}\u003c/artifactId\u003e\n        \u003cversion\u003e${lagom.openapi.version}\u003c/version\u003e\n    \u003c/dependency\u003e\n\u003c/dependencies\u003e\n```\n\n**Sbt**\n\n```scala\nval lagomOpenapiApi = \"org.taymyr.lagom\" %% \"lagom-openapi-java-api\" % lagomOpenapiVersion\n\nlazy val `lagom-service-api` = (project in file(\"api\"))\n  .settings(\n    libraryDependencies ++= Seq(\n      ...\n      lagomOpenapiApi\n    )\n  )\n```\n\nand next dependencies to the _Implementation_ module of Lagom service:\n\n**Maven**\n\n```xml\n\u003cdependencies\u003e\n    \u003cdependency\u003e\n        \u003cgroupId\u003eorg.taymyr.lagom\u003c/groupId\u003e\n        \u003cartifactId\u003elagom-openapi-java-impl_${scala.binary.version}\u003c/artifactId\u003e\n        \u003cversion\u003e${lagom.openapi.version}\u003c/version\u003e\n    \u003c/dependency\u003e\n\u003c/dependencies\u003e\n```\n\n**Sbt**\n\n```scala\nval lagomOpenapiImpl = \"org.taymyr.lagom\" %% \"lagom-openapi-java-impl\" % lagomOpenapiVersion\n\nlazy val `lagom-service-impl` = (project in file(\"impl\"))\n  .enablePlugins(LagomScala)\n  .settings(\n    libraryDependencies ++= Seq(\n      ...\n      lagomOpenapiImpl\n    )\n  )\n```\n\n### 2.2.2 Service Descriptor\n\n[*Only for Lagom 1.4.X*] Extend Lagom service descriptor by `OpenAPIService` interface:\n\n```java\npublic interface MyService extends OpenAPIService {\n  ...\n}\n```\n\nAdd OpenAPI/Swagger specification file to classpath (typically `src/main/resources` folder) of _API_ module. By default, the file should be named `\u003cservice_name\u003e.[yml|yaml|json]`.\n\n```yaml\nopenapi: 3.0.0\ninfo:\n  title: My Service\n  version: 1.0.0\npaths:\n  ...\n```\n\nAlso, you can change filename using `openapi.file` configuration in `application.conf`.\n\n```HOCON\nopenapi.file = foobar.yml\n```\n\n[*Only for Lagom 1.4.X*] In conclusion, you must add the route for OpenAPI specification. You can do that with helper function `org.taymyr.lagom.javadsl.openapi.OpenAPIUtils#withOpenAPI` (default route is `/_\u003cservice_name\u003e/openapi`)\n\n```java\n@Override\ndefault Descriptor descriptor() {\n  return withOpenAPI(\n    named(\"service\")\n      ...\n  );\n}\n```\n\nor use a custom route\n\n```java\n@Override\ndefault Descriptor descriptor() {\n  return named(\"service\")\n    .withCalls(\n      ...\n      pathCall(\"/custom/route?format\", this::openapi)\n    );\n}\n```\n\n### 2.2.3 Service implementation [Lagom 1.4.X]\n\nExtend your service by the abstract `AbstractOpenAPIService`:\n\n```java\npublic class MyServiceImpl extends AbstractOpenAPIService implements MyService {\n      ...\n}\n```\n\n### 2.2.4 Additional router [Lagom 1.5.X+]\n\nAdd [additional router](https://www.lagomframework.com/documentation/current/java/AdditionalRouters.html#Additional-Routers) for your service\n\n```java\n@Override\nprotected void configure() {\n    OpenAPIRouter openAPIRouter = new OpenAPIRouter(\n        getProvider(RoutingDsl.class),\n        getProvider(MyServiceImpl.class),\n        getProvider(Config.class)\n    );\n    bindService(MyService.class, MyServiceImpl.class, additionalRouter(openAPIRouter));\n}\n```\n\n\n### 2.2.5 Conclusion\n\nNow you can run service and get OpenAPI specification by a sent HTTP request to the registered route. For example by default:\n\n```bash\ncurl \"http://localhost:9000/_\u003cservice_name\u003e/openapi[?format=json|yaml]\"\n``` \n\n## Contributions\n\nContributions are very welcome.\n\n## License\n\nLicensed under the Apache License, Version 2.0 (the \"License\"); you may not use this project except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0.\n\nUnless required by applicable law or agreed to in writing, software distributed under the License is distributed on an \"AS IS\" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftaymyr%2Flagom-openapi","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftaymyr%2Flagom-openapi","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftaymyr%2Flagom-openapi/lists"}