OpenAPI/Swagger module for Lagom
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/Java DSL)
- Publishing static OpenAPI 3.X/Swagger 2.X specification from the classpath. (How to use with Scala DSL/Java DSL)
Also, you can see how to generate OpenAPI Specification for Lagom service on demo projects (Java/Maven example, Scala/Sbt example).
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+ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
[Only for Lagom 1.4.X] You need to add next dependencies to the API module of Lagom service:
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:
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
)
)
Necessarily add OpenAPIDefinition
annotation to Lagom service descriptor and extend (only for Lagom 1.4.X) descriptor by OpenAPIService
trait:
@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.
@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 /_<service_name>/openapi
)
override def descriptor: Descriptor = named("service")
.withOpenAPI()
...
or use a custom route
override def descriptor: Descriptor = named("service")
.withCalls(
...
pathCall("/custom/route", openapi)
)
Extend your service by the OpenAPIServiceImpl
trait:
class MyServiceImpl(override val config: Config)
extends MyService
with OpenAPIServiceImpl {
...
}
Add additional router for your service
override lazy val lagomServer = {
val service = wire[PetsServiceImpl]
serverFor[PetsService](service)
.additionalRouter(wire[OpenAPIRouter].router(service))
}
Now you can run service and get OpenAPI specification by a sent HTTP request to the registered route. For example by default:
curl "http://localhost:9000/_<service_name>/openapi[?format=json|yaml]"
[Only for Lagom 1.4.X] You need to add next dependencies to the API module of Lagom service:
Maven
<dependencies>
<dependency>
<groupId>org.taymyr.lagom</groupId>
<artifactId>lagom-openapi-java-api_${scala.binary.version}</artifactId>
<version>${lagom.openapi.version}</version>
</dependency>
<dependency>
<groupId>io.swagger.core.v3</groupId>
<artifactId>swagger-annotations</artifactId>
<version>2.0.7</version>
</dependency>
</dependencies>
Sbt
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
<dependencies>
<dependency>
<groupId>org.taymyr.lagom</groupId>
<artifactId>lagom-openapi-java-impl_${scala.binary.version}</artifactId>
<version>${lagom.openapi.version}</version>
</dependency>
</dependencies>
Sbt
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
)
)
Necessarily add OpenAPIDefinition
annotation to Lagom service descriptor and extend (only for Lagom 1.4.X) descriptor by OpenAPIService
interface:
@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.
@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 /_<service_name>/openapi
)
@Override
default Descriptor descriptor() {
return withOpenAPI(
named("service")
...
);
}
or use a custom route
@Override
default Descriptor descriptor() {
return named("service")
.withCalls(
...
pathCall("/custom/route", this::openapi)
);
}
[Only for Lagom 1.4.X] Extend your service by the abstract AbstractOpenAPIService
:
public class MyServiceImpl extends AbstractOpenAPIService implements MyService {
...
}
Add additional router for your service
@Override
protected void configure() {
OpenAPIRouter openAPIRouter = new OpenAPIRouter(
getProvider(RoutingDsl.class),
getProvider(MyServiceImpl.class),
getProvider(Config.class)
);
bindService(MyService.class, MyServiceImpl.class, additionalRouter(openAPIRouter));
}
Now you can run service and get OpenAPI specification by a sent HTTP request to the registered route. For example by default:
curl "http://localhost:9000/_<service_name>/openapi[?format=json|yaml]"
[Only for Lagom 1.4.X] You need to add next dependencies to the API module of Lagom service:
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:
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
)
)
[Only for Lagom 1.4.X] Extend Lagom service descriptor by OpenAPIService
trait:
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 <service_name>.[yml|yaml|json]
.
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
.
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 /_<service_name>/openapi
)
override def descriptor: Descriptor = withOpenAPI(
named("service")
...
)
or use a custom route
override def descriptor: Descriptor = named("service")
.withCalls(
...
pathCall("/custom/route?format", openapi)
)
[Only for Lagom 1.4.X] Extend your service by the OpenAPIServiceImpl
trait:
class MyServiceImpl(override val config: Config)
extends MyService
with OpenAPIServiceImpl {
...
}
Add additional router for your service
override lazy val lagomServer = {
val service = wire[PetsServiceImpl]
serverFor[PetsService](service)
.additionalRouter(wire[OpenAPIRouter].router(service))
}
Now you can run service and get OpenAPI specification by a sent HTTP request to the registered route. For example by default:
curl "http://localhost:9000/_<service_name>/openapi[?format=json|yaml]"
[Only for Lagom 1.4.X] You need to add next dependencies to the API module of Lagom service:
Maven
<dependencies>
<dependency>
<groupId>org.taymyr.lagom</groupId>
<artifactId>lagom-openapi-java-api_${scala.binary.version}</artifactId>
<version>${lagom.openapi.version}</version>
</dependency>
</dependencies>
Sbt
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
<dependencies>
<dependency>
<groupId>org.taymyr.lagom</groupId>
<artifactId>lagom-openapi-java-impl_${scala.binary.version}</artifactId>
<version>${lagom.openapi.version}</version>
</dependency>
</dependencies>
Sbt
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
)
)
[Only for Lagom 1.4.X] Extend Lagom service descriptor by OpenAPIService
interface:
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 <service_name>.[yml|yaml|json]
.
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
.
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 /_<service_name>/openapi
)
@Override
default Descriptor descriptor() {
return withOpenAPI(
named("service")
...
);
}
or use a custom route
@Override
default Descriptor descriptor() {
return named("service")
.withCalls(
...
pathCall("/custom/route?format", this::openapi)
);
}
Extend your service by the abstract AbstractOpenAPIService
:
public class MyServiceImpl extends AbstractOpenAPIService implements MyService {
...
}
Add additional router for your service
@Override
protected void configure() {
OpenAPIRouter openAPIRouter = new OpenAPIRouter(
getProvider(RoutingDsl.class),
getProvider(MyServiceImpl.class),
getProvider(Config.class)
);
bindService(MyService.class, MyServiceImpl.class, additionalRouter(openAPIRouter));
}
Now you can run service and get OpenAPI specification by a sent HTTP request to the registered route. For example by default:
curl "http://localhost:9000/_<service_name>/openapi[?format=json|yaml]"
Contributions are very welcome.
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.