Lagom REST API documentation

(Vimal Mishrra) #1

What support does lagom provide to create documentation for REST API/services created ? Like Spring has support for Swagger, is there some lagom specific tool/component that we need to use to create the documentation for developers. Can swagger be integrated with Lagom ? Is there an example that I can see and use ?

(Sergey Morgunov) #2

Until Lagom does not support integration with Swagger.

And doesn’t stable.

For our services, we create swagger docs manually and use for share docs.

(Vimal Mishrra) #3

So if I have to use to generate documentation for my Lagom REST services, I simply download this code and run it as a lagom service locally ?

(Sergey Morgunov) #4

No, this library does not generate documentation. It just finding it in the classpath and create a route to share it. For example:

  1. You have a service with name myservice.
  2. Add dependencies for api and implementation:
val lagomOpenApiJavaApi = "org.taymyr.lagom" % "lagom-openapi-java-api" % "0.0.2"
val lagomOpenApiJavaImpl = "org.taymyr.lagom" % "lagom-openapi-java-impl" % "0.0.2"
  1. Add file myservice.yml to myservice-api/src/main/resources/
  2. Service descriptor must extend interface OpenAPIService and use method withOpenAPI for wrap descriptor:
public interface MyService extends OpenAPIService {
    default Descriptor descriptor() {
        return withOpenAPI(named("myservice"))
  1. Service implementation must extend AbstractOpenAPIService:
public class MyServiceImpl extends AbstractOpenAPIService implements MyService {

After, you can get swagger docs by path /_myservice/openapi and use this route in Swagger UI.

(Vimal Mishrra) #5

Thanks a lot. Really appreciate the effort.