Lagom REST API documentation

[vimalmishrra]

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 ?

[ihostage (Sergey Morgunov)]

Until Lagom does not support integration with Swagger.

Issue: Support Swagger docs in Lagom

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.

[vimalmishrra]

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 ?

[ihostage (Sergey Morgunov)]

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"

3. Add file myservice.yml to myservice-api/src/main/resources/
4. 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);
    }
}

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

[vimalmishrra]

Thanks a lot. Really appreciate the effort.

[ihostage (Sergey Morgunov)]

Lagom OpenAPI 1.0.0 released!

The Taymyr Team is pleased to announce the release 1.0.0 of OpenAPI module. This is the first stable release with support Lagom Scala DSL and feature autogenerate OpenAPI 3.X specification by annotations. Also, our team created two examples (Java/Maven example, Scala/Sbt example) for demonstrate how you can generate OpenAPI Specification by annotations.

[popprem (Prasath P)]

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)

[ihostage (Sergey Morgunov)]

Hi, @popprem!

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