Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/taymyr/lagom-openapi
OpenAPI/Swagger module for Lagom
https://github.com/taymyr/lagom-openapi
lagom openapi swagger
Last synced: about 2 months ago
JSON representation
OpenAPI/Swagger module for Lagom
- Host: GitHub
- URL: https://github.com/taymyr/lagom-openapi
- Owner: taymyr
- License: apache-2.0
- Created: 2018-09-11T15:01:02.000Z (over 6 years ago)
- Default Branch: master
- Last Pushed: 2021-11-19T06:52:10.000Z (about 3 years ago)
- Last Synced: 2023-10-30T09:16:46.044Z (about 1 year ago)
- Topics: lagom, openapi, swagger
- Language: Kotlin
- Homepage:
- Size: 337 KB
- Stars: 36
- Watchers: 4
- Forks: 10
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
[](https://gitter.im/taymyr/taymyr)
[](https://gitter.im/taymyr/taymyr_ru)
[](https://travis-ci.org/taymyr/lagom-openapi)
[](https://codecov.io/gh/taymyr/lagom-openapi)
[](https://search.maven.org/search?q=a:lagom-openapi-*2.12%20AND%20g:org.taymyr.lagom)
# [OpenAPI/Swagger](https://swagger.io/specification/) module for [Lagom](https://www.lagomframework.com)
The Lagom OpenAPI module has two common features:
* 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))
* 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))
Also, 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)).
## Versions compatibility
| Lagom OpenAPI | OpenAPI / Swagger | Lagom 1.4 | Lagom 1.5 | Lagom 1.6 | Scala 2.11 | Scala 2.12 | Scala 2.13 |
|:-------------:|:-----------------:|:------------------:|:------------------:|:------------------:|:------------------:|:------------------:|:------------------:|
| 1.+ | 2.0.7+ | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: |
# How to use
## 1.1 Generate (Scala DSL)
### 1.1.1 Dependencies
[*Only for Lagom 1.4.X*] You need to add next dependencies to the _API_ module of Lagom service:
```scala
val swaggerAnnotations = "io.swagger.core.v3" % "swagger-annotations" % "2.0.7"
val lagomOpenapiApi = "org.taymyr.lagom" %% "lagom-openapi-scala-api" % lagomOpenapiVersion
lazy val `lagom-service-api` = (project in file("api"))
.settings(
libraryDependencies ++= Seq(
...
swaggerAnnotations,
lagomOpenapiApi
)
)
```
and next dependencies to the _Implementation_ module of Lagom service:
```scala
val lagomOpenapiImpl = "org.taymyr.lagom" %% "lagom-openapi-scala-impl" % lagomOpenapiVersion
lazy val `lagom-service-impl` = (project in file("impl"))
.enablePlugins(LagomScala)
.settings(
libraryDependencies ++= Seq(
...
lagomOpenapiImpl
)
)
```
### 1.1.2 Service Descriptor
Necessarily add `OpenAPIDefinition` annotation to Lagom service descriptor and extend (*only for Lagom 1.4.X*) descriptor by `OpenAPIService` trait:
```scala
@OpenAPIDefinition(
info = new Info(
version = "1.0.0",
title = "My Service"
),
...
)
trait MyService extends OpenAPIService with Service {
...
}
```
Then 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).
```scala
@Operation(...)
@Tag(...)
...
def method: ServiceCall[_, _]
```
[*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 `/_/openapi`)
```scala
override def descriptor: Descriptor = named("service")
.withOpenAPI()
...
```
or use a custom route
```scala
override def descriptor: Descriptor = named("service")
.withCalls(
...
pathCall("/custom/route", openapi)
)
```
### 1.1.3 Service implementation [Lagom 1.4.X]
Extend your service by the `OpenAPIServiceImpl` trait:
```scala
class MyServiceImpl(override val config: Config)
extends MyService
with OpenAPIServiceImpl {
...
}
```
### 1.1.4 Additional router [Lagom 1.5.X+]
Add [additional router](https://www.lagomframework.com/documentation/current/scala/AdditionalRouters.html#Additional-Routers) for your service
```scala
override lazy val lagomServer = {
val service = wire[PetsServiceImpl]
serverFor[PetsService](service)
.additionalRouter(wire[OpenAPIRouter].router(service))
}
```
### 1.1.5 Conclusion
Now you can run service and get OpenAPI specification by a sent HTTP request to the registered route. For example by default:
```bash
curl "http://localhost:9000/_/openapi[?format=json|yaml]"
```
## 1.2 Generate (Java DSL)
### 1.2.1 Dependencies
[*Only for Lagom 1.4.X*] You need to add next dependencies to the _API_ module of Lagom service:
**Maven**
```xml
org.taymyr.lagom
lagom-openapi-java-api_${scala.binary.version}
${lagom.openapi.version}
io.swagger.core.v3
swagger-annotations
2.0.7
```
**Sbt**
```scala
val swaggerAnnotations = "io.swagger.core.v3" % "swagger-annotations" % "2.0.7"
val lagomOpenapiApi = "org.taymyr.lagom" %% "lagom-openapi-java-api" % lagomOpenapiVersion
lazy val `lagom-service-api` = (project in file("api"))
.settings(
libraryDependencies ++= Seq(
...
swaggerAnnotations,
lagomOpenapiApi
)
)
```
and next dependencies to the _Implementation_ module of Lagom service:
**Maven**
```xml
org.taymyr.lagom
lagom-openapi-java-impl_${scala.binary.version}
${lagom.openapi.version}
```
**Sbt**
```scala
val lagomOpenapiImpl = "org.taymyr.lagom" %% "lagom-openapi-java-impl" % lagomOpenapiVersion
lazy val `lagom-service-impl` = (project in file("impl"))
.enablePlugins(LagomScala)
.settings(
libraryDependencies ++= Seq(
...
lagomOpenapiImpl
)
)
```
### 1.2.2 Service Descriptor
Necessarily add `OpenAPIDefinition` annotation to Lagom service descriptor and extend (*only for Lagom 1.4.X*) descriptor by `OpenAPIService` interface:
```java
@OpenAPIDefinition(
info = @Info(
version = "1.0.0",
title = "My Service"
),
...
)
public interface MyService extends OpenAPIService {
...
}
```
Then 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).
```java
@Operation(...)
@Tag(...)
...
ServiceCall<_, _> method();
```
[*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 `/_/openapi`)
```java
@Override
default Descriptor descriptor() {
return withOpenAPI(
named("service")
...
);
}
```
or use a custom route
```java
@Override
default Descriptor descriptor() {
return named("service")
.withCalls(
...
pathCall("/custom/route", this::openapi)
);
}
```
### 1.2.3 Service implementation [Lagom 1.4.X]
[*Only for Lagom 1.4.X*] Extend your service by the abstract `AbstractOpenAPIService`:
```java
public class MyServiceImpl extends AbstractOpenAPIService implements MyService {
...
}
```
### 1.2.4 Additional router [Lagom 1.5.X+]
Add [additional router](https://www.lagomframework.com/documentation/current/java/AdditionalRouters.html#Additional-Routers) for your service
```java
@Override
protected void configure() {
OpenAPIRouter openAPIRouter = new OpenAPIRouter(
getProvider(RoutingDsl.class),
getProvider(MyServiceImpl.class),
getProvider(Config.class)
);
bindService(MyService.class, MyServiceImpl.class, additionalRouter(openAPIRouter));
}
```
### 1.2.5 Conclusion
Now you can run service and get OpenAPI specification by a sent HTTP request to the registered route. For example by default:
```bash
curl "http://localhost:9000/_/openapi[?format=json|yaml]"
```
## 2.1 Static (Scala DSL)
### 2.1.1 Dependencies
[*Only for Lagom 1.4.X*] You need to add next dependencies to the _API_ module of Lagom service:
```scala
val lagomOpenapiApi = "org.taymyr.lagom" %% "lagom-openapi-scala-api" % lagomOpenapiVersion
lazy val `lagom-service-api` = (project in file("api"))
.settings(
libraryDependencies ++= Seq(
...
lagomOpenapiApi
)
)
```
and next dependencies to the _Implementation_ module of Lagom service:
```scala
val lagomOpenapiImpl = "org.taymyr.lagom" %% "lagom-openapi-scala-impl" % lagomOpenapiVersion
lazy val `lagom-service-impl` = (project in file("impl"))
.enablePlugins(LagomScala)
.settings(
libraryDependencies ++= Seq(
...
lagomOpenapiImpl
)
)
```
### 2.1.2 Service Descriptor
[*Only for Lagom 1.4.X*] Extend Lagom service descriptor by `OpenAPIService` trait:
```scala
trait MyService extends OpenAPIService with Service {
...
}
```
Add OpenAPI/Swagger specification file to classpath (typically `src/main/resources` folder) of _API_ module. By default, the file should be named `.[yml|yaml|json]`.
```yaml
openapi: 3.0.0
info:
title: My Service
version: 1.0.0
paths:
...
```
Also, you can change filename using `openapi.file` configuration in `application.conf`.
```HOCON
openapi.file = foobar.yml
```
[*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 `/_/openapi`)
```scala
override def descriptor: Descriptor = withOpenAPI(
named("service")
...
)
```
or use a custom route
```scala
override def descriptor: Descriptor = named("service")
.withCalls(
...
pathCall("/custom/route?format", openapi)
)
```
### 2.1.3 Service implementation [Lagom 1.4.X]
[*Only for Lagom 1.4.X*] Extend your service by the `OpenAPIServiceImpl` trait:
```scala
class MyServiceImpl(override val config: Config)
extends MyService
with OpenAPIServiceImpl {
...
}
```
### 2.1.4 Additional router [Lagom 1.5.X+]
Add [additional router](https://www.lagomframework.com/documentation/current/scala/AdditionalRouters.html#Additional-Routers) for your service
```scala
override lazy val lagomServer = {
val service = wire[PetsServiceImpl]
serverFor[PetsService](service)
.additionalRouter(wire[OpenAPIRouter].router(service))
}
```
### 2.1.5 Conclusion
Now you can run service and get OpenAPI specification by a sent HTTP request to the registered route. For example by default:
```bash
curl "http://localhost:9000/_/openapi[?format=json|yaml]"
```
## 2.2 Static (Java DSL)
### 2.2.1 Dependencies
[*Only for Lagom 1.4.X*] You need to add next dependencies to the _API_ module of Lagom service:
**Maven**
```xml
org.taymyr.lagom
lagom-openapi-java-api_${scala.binary.version}
${lagom.openapi.version}
```
**Sbt**
```scala
val lagomOpenapiApi = "org.taymyr.lagom" %% "lagom-openapi-java-api" % lagomOpenapiVersion
lazy val `lagom-service-api` = (project in file("api"))
.settings(
libraryDependencies ++= Seq(
...
lagomOpenapiApi
)
)
```
and next dependencies to the _Implementation_ module of Lagom service:
**Maven**
```xml
org.taymyr.lagom
lagom-openapi-java-impl_${scala.binary.version}
${lagom.openapi.version}
```
**Sbt**
```scala
val lagomOpenapiImpl = "org.taymyr.lagom" %% "lagom-openapi-java-impl" % lagomOpenapiVersion
lazy val `lagom-service-impl` = (project in file("impl"))
.enablePlugins(LagomScala)
.settings(
libraryDependencies ++= Seq(
...
lagomOpenapiImpl
)
)
```
### 2.2.2 Service Descriptor
[*Only for Lagom 1.4.X*] Extend Lagom service descriptor by `OpenAPIService` interface:
```java
public interface MyService extends OpenAPIService {
...
}
```
Add OpenAPI/Swagger specification file to classpath (typically `src/main/resources` folder) of _API_ module. By default, the file should be named `.[yml|yaml|json]`.
```yaml
openapi: 3.0.0
info:
title: My Service
version: 1.0.0
paths:
...
```
Also, you can change filename using `openapi.file` configuration in `application.conf`.
```HOCON
openapi.file = foobar.yml
```
[*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 `/_/openapi`)
```java
@Override
default Descriptor descriptor() {
return withOpenAPI(
named("service")
...
);
}
```
or use a custom route
```java
@Override
default Descriptor descriptor() {
return named("service")
.withCalls(
...
pathCall("/custom/route?format", this::openapi)
);
}
```
### 2.2.3 Service implementation [Lagom 1.4.X]
Extend your service by the abstract `AbstractOpenAPIService`:
```java
public class MyServiceImpl extends AbstractOpenAPIService implements MyService {
...
}
```
### 2.2.4 Additional router [Lagom 1.5.X+]
Add [additional router](https://www.lagomframework.com/documentation/current/java/AdditionalRouters.html#Additional-Routers) for your service
```java
@Override
protected void configure() {
OpenAPIRouter openAPIRouter = new OpenAPIRouter(
getProvider(RoutingDsl.class),
getProvider(MyServiceImpl.class),
getProvider(Config.class)
);
bindService(MyService.class, MyServiceImpl.class, additionalRouter(openAPIRouter));
}
```
### 2.2.5 Conclusion
Now you can run service and get OpenAPI specification by a sent HTTP request to the registered route. For example by default:
```bash
curl "http://localhost:9000/_/openapi[?format=json|yaml]"
```
## Contributions
Contributions are very welcome.
## License
Licensed 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.
Unless 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.