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 https://github.com/lagom/sbt-lagom-descriptor-generator doesn’t stable.

For our services, we create swagger docs manually and use https://github.com/taymyr/lagom-openapi-java/ for share docs.

(Vimal Mishrra) #3

So if I have to use https://github.com/taymyr/lagom-openapi-java/ 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 {
  @Override
    default Descriptor descriptor() {
        return withOpenAPI(named("myservice"))
                .withCalls(
                    ...
                )
                .withAutoAcl(true);
    }
}
  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.