Expose shlink's API endpoints via swagger ui while running Docker image

[bbednarek]

Shlink version

All

PHP version

All

How do you serve Shlink

RoadRunner Docker image

Database engine

SQLite

Database version

N/A

Summary

I'd like to have some API path which would expose shlink's swagger ui (sth similar to this one in the documentation), which is matching API definition of the respective version eg. 3.6.3.
The use case is on test env only, so people can play around with it.

For example if I run the docker locally it would be

http://localhost:8080/swagger-ui

Is there such possibility?

[acelaya]

What I usually do is have a swagger-ui dist copy inside the docs folder (you'll notice it is gitignored), and point the url to the local swagger.json file.

You can download latest's swagger-ui from here https://github.com/swagger-api/swagger-ui/archive/refs/heads/master.zip, then pick dist's directory contents.

Then you'll need some way to serve the local swagger-ui. If you use WebStorm, it has a way to spin-up a static file server by right-clicking swagger-ui's index.html file -> "Open in" -> "Browser".

That said, I could explore including a copy and serve it with the project itself.

[bbednarek]

Thanks for the heads up!

It would be great to serve swagger ui with the project itself hidden behind some feature flag exposed via env var.

[acelaya]

I picture it more like a separated container. The project already ships with a bunch of docker containers for dev, so there could be one serving swagger-ui (nginx serving static assets, a nodejs server... There are options).

Then you would have it on a different port, for example, localhost:8005/swagger-ui. This way there's no need to deal with env vars or anything, as Shlink's core is not affected.

[acelaya]

If you apply this diff to the docker-compose.yml file, you'll have a swagger-ui on http://localhost:8005 which serves the Open API spec from docs/swagger.

diff --git a/docker-compose.yml b/docker-compose.yml
index ca0064b4..9f3a01a1 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -193,3 +193,11 @@ services:
         environment:
             RABBITMQ_DEFAULT_USER: "rabbit"
             RABBITMQ_DEFAULT_PASS: "rabbit"
+
+    shlink_swagger_ui:
+        container_name: shlink_swagger_ui
+        image: swaggerapi/swagger-ui:v5.7.1
+        ports:
+            - "8005:8080"
+        volumes:
+            - ./docs/swagger:/app

I'll push this change soon to develop.