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).

Versions compatibility

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:

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
    )
  )

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:

@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)
    )

1.1.3 Service implementation [Lagom 1.4.X]

Extend your service by the OpenAPIServiceImpl trait:

class MyServiceImpl(override val config: Config)
    extends MyService
    with OpenAPIServiceImpl {
      ...
}

1.1.4 Additional router [Lagom 1.5.X+]

Add additional router for your service

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:

curl "http://localhost:9000/_<service_name>/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

<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
    )
  )

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:

@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)
    );
}

1.2.3 Service implementation [Lagom 1.4.X]

[Only for Lagom 1.4.X] Extend your service by the abstract AbstractOpenAPIService:

public class MyServiceImpl extends AbstractOpenAPIService implements MyService {
      ...
}

1.2.4 Additional router [Lagom 1.5.X+]

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));
}

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:

curl "http://localhost:9000/_<service_name>/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:

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
    )
  )

2.1.2 Service Descriptor

[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)
    )

2.1.3 Service implementation [Lagom 1.4.X]

[Only for Lagom 1.4.X] Extend your service by the OpenAPIServiceImpl trait:

class MyServiceImpl(override val config: Config)
    extends MyService
    with OpenAPIServiceImpl {
      ...
}

2.1.4 Additional router [Lagom 1.5.X+]

Add additional router for your service

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:

curl "http://localhost:9000/_<service_name>/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

<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
    )
  )

2.2.2 Service Descriptor

[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)
    );
}

2.2.3 Service implementation [Lagom 1.4.X]

Extend your service by the abstract AbstractOpenAPIService:

public class MyServiceImpl extends AbstractOpenAPIService implements MyService {
      ...
}

2.2.4 Additional router [Lagom 1.5.X+]

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));
}

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:

curl "http://localhost:9000/_<service_name>/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.