Lagom REST API documentation

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 ?

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.

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 ?

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.

Thanks a lot. Really appreciate the effort.

This is great @ihostage, I tried using it and generated the specs successfully, Thanks.

Is there a way to integrate the swagger UI (or any other UIs) and show the specs using it as part of the project? (Not by running the swagger UI dist seperately)

Hi, @popprem! :wave:

I think it’s possible with Lagom additionalRouter feature. But this task is not in our immediate plans. We plan to realize exactly separate service, that collects Swagger JSON from all our services and show it on centralized Swagger UI. We sure will announce when implemented and shared it on GitHub.

Regards,
Sergey

1 Like