Is there any way to generate swagger-ui endpoints?

[alexklibisz]

Hi, neat project!

I just want to see if there is some way to generate the Swagger UI HTML/CSS/JS artifacts that need to be served up in order to get Swagger UI running?

[blast-hardcheese]

Hey Alex, thanks!

I know others at Twilio spent some time getting that working in-house, but it never made it to OSS.

The mission statement of this project is to ensure it's as easy as possible to follow your specification in a type-safe and idiomatic way, while exposing the underlying routing infrastructure for whatever framework you're using. The latter being a great launching off point for integrating with other stuff (the output of a dedicated swagger-ui plugin, existing routing infrastructure that hasn't been converted to guardrail yet, etc)

I'm not opposed to it, I just don't know what that would look like.

[alexklibisz]

Thanks Devon. I did a bit more digging. I think it might be better to keep this out of guardrail. There are a few scala/swagger-ui integrations floating around, but I actually think something like this might be simpler..

Expose the openapi yaml through the server, something like:

val appRoutes: Route = PetResource.routes(...)
val docsRoutes: Route = path("openapi.yaml") {
    getFromResource("petstore.yaml", ContentType(MediaType.customWithFixedCharset("text", "vnd.yaml", `UTF-8`)))
  }
 Await.result(Http().newServerAt("0.0.0.0", 8080).bindFlow(appRoutes ~ docsRoutes), Duration.Inf)

Then just run the swagger-ui docker container and point it at the https://<my service>/openapi.yaml URL.

Spinning up an official docker container is a lot easier than messing with the various language-specific swagger-ui server implementations.

So, maybe the only thing that would be useful to implement in guardrail is the ability to copy the openapi yaml spec into src_managed. That would make it easier to serve the openapi spec from a dockerized akka-http server. Otherwise, we'd have to either remember to copy it into the container, or mount it, or would have to keep it in src/main/resources.

[blast-hardcheese]

That's not out the realm of possibility, it would go well alongside the different kinds we support, to go alongside client, server, and models. Probably spec, though that's available for bikeshedding.

One possible benefit is that by round-tripping through the OpenAPI parser, I presume it would inline all cross-file references and omit unexpected or unusable fields. External file references was an issue we dealt with when trying to do swagger-ui, iirc.