Add a centralized Swagger-UI for all OpenAPI specs

README.md

@@ -84,7 +84,7 @@ Here's the summary of the profiles and what services they includes:
 | rabbitmq<br/>postgres<br/>elasticsearch | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | |
 | kibana<br/>logstash<br/>socat<br/>logspout | | | | | | | | | ✅ | | |
 | pgadmin | | | | | | | | | | ✅ | |
-| apps&#8209;metadata&#8209;server<br/>mock&#8209;user&#8209;service<br/>gateway<br/>actions&#8209;server<br/>case&#8209;server<br/>config&#8209;notification&#8209;server<br/>config&#8209;server<br/>filter&#8209;server<br/>loadflow&#8209;server<br/>network&#8209;conversion&#8209;server<br/>network&#8209;store&#8209;server<br/>report&#8209;server<br/>user&#8209;admin&#8209;server | | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | | |
+| apps&#8209;metadata&#8209;server<br/>mock&#8209;user&#8209;service<br/>gateway<br/>actions&#8209;server<br/>case&#8209;server<br/>config&#8209;notification&#8209;server<br/>config&#8209;server<br/>filter&#8209;server<br/>loadflow&#8209;server<br/>network&#8209;conversion&#8209;server<br/>network&#8209;store&#8209;server<br/>spreadsheet&#8209;config&#8209;server<br/>report&#8209;server<br/>user&#8209;admin&#8209;server | | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | | |
 | griddyna&#8209;app<br/>dynamic&#8209;mapping&#8209;server | | | | | ✅ | ✅ | ✅ | | | | |
 | gridmerge&#8209;app<br/>balances&#8209;adjustment&#8209;server<br/>case&#8209;import&#8209;job<br/>case&#8209;validation&#8209;server<br/>cgmes&#8209;assembling&#8209;job<br/>cgmes&#8209;boundary&#8209;import&#8209;job<br/>cgmes&#8209;boundary&#8209;server<br/>merge&#8209;notification&#8209;server<br/>merge&#8209;orchestrator&#8209;server | | ✅ | | | | | ✅ | | | | |
 | gridstudy&#8209;app<br/>dynamic&#8209;simulation&#8209;server<br/>timeseries&#8209;server | | | ✅ | | | ✅ | ✅ | | | | |
@@ -176,49 +176,47 @@ $ docker image prune -f
 
 You can now access to all applications and swagger UIs of the Spring services of the chosen profile:
 
-Applications:
-```html
-http://localhost:80 // gridexplore
-http://localhost:81 // gridmerge
-http://localhost:82 // gridadmin
-http://localhost:83 // griddyna
-http://localhost:84 // gridstudy
-```
+- Applications:
+  - http://localhost:80 :: gridexplore
+  - http://localhost:81 :: gridmerge
+  - http://localhost:82 :: gridadmin
+  - http://localhost:83 :: griddyna
+  - http://localhost:84 :: gridstudy
+
+- Aggregated Swagger-UI: http://localhost:9080/swagger/
+- Swagger-UI per server:
+  - http://localhost:5000/swagger-ui.html :: case-server
+  - http://localhost:8095/swagger-ui.html :: cgmes-gl-server
+  - http://localhost:8087/swagger-ui.html :: geo-data-server
+  - http://localhost:5003/swagger-ui.html :: network-conversion-server
+  - http://localhost:8080/swagger-ui.html :: network-store-server
+  - http://localhost:5006/swagger-ui.html :: network-map-server
+  - http://localhost:8090/swagger-ui.html :: odre-server
+  - http://localhost:5005/swagger-ui.html :: single-line-diagram-server
+  - http://localhost:5001/swagger-ui.html :: study-server
+  - http://localhost:5007/swagger-ui.html :: network-modification-server
+  - http://localhost:5008/swagger-ui.html :: loadflow-server
+  - http://localhost:5020/swagger-ui.html :: merge-orchestrator-server
+  - http://localhost:5021/swagger-ui.html :: cgmes-boundary-server
+  - http://localhost:5022/swagger-ui.html :: actions-server
+  - http://localhost:5023/swagger-ui.html :: security-analysis-server
+  - http://localhost:5025/swagger-ui.html :: config-server
+  - http://localhost:5026/swagger-ui.html :: directory-server
+  - http://localhost:5028/swagger-ui.html :: report-server
+  - http://localhost:5029/swagger-ui.html :: explore-server
+  - http://localhost:5036/swagger-ui.html :: dynamic-mapping-server
+  - http://localhost:5032/swagger-ui.html :: dynamic-simulation-server
+  - http://localhost:5027/swagger-ui.html :: filter-server
+  - http://localhost:5010/swagger-ui.html :: balances-adjustment-server
+  - http://localhost:5011/swagger-ui.html :: case-validation-server
+  - http://localhost:5033/swagger-ui.html :: user-admin-server
+  - http://localhost:5030/swagger-ui.html :: sensitivity-analysis-server
+  - http://localhost:5031/swagger-ui.html :: shortcircuit-server
+  - http://localhost:5035/swagger-ui.html :: spreadsheet-config-server
+  - http://localhost:5037/swagger-ui.html :: timeseries-server
+  - http://localhost:5038/swagger-ui.html :: voltage-init-server
+  - http://localhost:5039/swagger-ui.html :: case-import-server
 
-Swagger UI:
-```html
-http://localhost:5000/swagger-ui.html  // case-server
-http://localhost:8095/swagger-ui.html  // cgmes-gl-server
-http://localhost:8087/swagger-ui.html  // geo-data-server
-http://localhost:5003/swagger-ui.html  // network-conversion-server
-http://localhost:8080/swagger-ui.html  // network-store-server
-http://localhost:5006/swagger-ui.html  // network-map-server
-http://localhost:8090/swagger-ui.html  // odre-server
-http://localhost:5005/swagger-ui.html  // single-line-diagram-server
-http://localhost:5001/swagger-ui.html  // study-server
-http://localhost:5007/swagger-ui.html  // network-modification-server
-http://localhost:5008/swagger-ui.html  // loadflow-server
-http://localhost:5020/swagger-ui.html  // merge-orchestrator-server
-http://localhost:5021/swagger-ui.html  // cgmes-boundary-server
-http://localhost:5022/swagger-ui.html  // actions-server
-http://localhost:5023/swagger-ui.html  // security-analysis-server
-http://localhost:5025/swagger-ui.html  // config-server
-http://localhost:5026/swagger-ui.html  // directory-server
-http://localhost:5028/swagger-ui.html  // report-server
-http://localhost:5029/swagger-ui.html  // explore-server
-http://localhost:5036/swagger-ui.html  // dynamic-mapping-server
-http://localhost:5032/swagger-ui.html  // dynamic-simulation-server
-http://localhost:5027/swagger-ui.html  // filter-server
-http://localhost:5010/swagger-ui.html  // balances-adjustment-server
-http://localhost:5011/swagger-ui.html  // case-validation-server
-http://localhost:5033/swagger-ui.html  // user-admin-server
-http://localhost:5030/swagger-ui.html  // sensitivity-analysis-server
-http://localhost:5031/swagger-ui.html  // shortcircuit-server
-http://localhost:5035/swagger-ui.html  // spreadsheet-config-server
-http://localhost:5037/swagger-ui.html  // timeseries-server
-http://localhost:5038/swagger-ui.html  // voltage-init-server
-http://localhost:5039/swagger-ui.html  // case-import-server
-```
 
 ### RabbitMQ console
 
@@ -292,6 +290,18 @@ You must get this output from docker compose now:
 > The commands shown will install the plugin user-side, so you don't need to remove your old docker-compose v1 if it is installed system-wide.
 
 
+### Tips & tricks
+
+#### Some commands that can be useful
+```shell
+# Get all services that have ports bound on host
+docker compose --profile all config --services | xargs printf -- 'grid-%s-1\n' | tr '\n' ' ' | xargs docker inspect | jq 'map( { (.Name|tostring): .HostConfig.PortBindings } ) | add'
+
+# Get the list of all ports bound on host
+docker compose --profile all config --services | xargs printf -- 'grid-%s-1\n' | tr '\n' ' ' | xargs docker inspect | jq 'map(.HostConfig.PortBindings[] | add | .HostPort | tonumber) | . + [3000,3001,3002,3003,3004,5035,5041] | sort'
+```
+
+
 ## k8s deployment with Minikube
 
 ### Minikube and kubectl setup

docker-compose/technical/docker-compose.technical.yml

@@ -187,3 +187,45 @@ services:
       - GF_ANALYTICS_CHECK_FOR_UPDATES=false
     ports:
       - "7000:3000"
+
+  # accessible at http://localhost:9080/swagger/
+  swagger-ui:
+    #profiles: all
+    image: swaggerapi/swagger-ui:latest
+    build: ./technical/swagger
+    restart: unless-stopped
+    deploy:
+      replicas: 1
+      #restart_policy:
+      #  condition: on-failure
+      #  delay: 5s
+      #  max_attempts: 3
+      #  window: 20s
+      resources:
+        # use ~14MB RAM when tested
+        limits:
+          # we limit the number of worker processes nginx create
+          cpus: '1'
+          memory: 50M
+        reservations:
+          memory: 20M
+    ports:
+      - 9080:8080
+    extra_hosts:
+      - "host.docker.internal:host-gateway"
+    environment:
+      NGINX_ENTRYPOINT_WORKER_PROCESSES_AUTOTUNE: true  # with deploy limits, will redduce the number of wrokers
+      BASE_URL: /swagger
+      #TRY_IT_OUT_ENABLED: true  #enable "Try it out" by default
+      URLS_PRIMARY_NAME: gateway
+      URLS: >
+        [
+        {"url":"https://github.com/elastic/elasticsearch-specification/raw/8.12/output/openapi/elasticsearch-serverless-openapi.json","name":"ElasticSearch API"},
+        {"url":"https://github.com/elastic/kibana/raw/refs/tags/v8.7.1/x-pack/plugins/fleet/common/openapi/bundled.json","name":"Kibana plugin Fleet API"}
+        ]
+      # no spec found for:
+      #   https://rawcdn.githack.com/rabbitmq/rabbitmq-server/v3.13.7/deps/rabbitmq_management/priv/www/api/index.html
+      #   https://github.com/prometheus/prometheus/blob/main/docs/querying/api.md?plain=1
+      #     https://prometheus.io/docs/prometheus/latest/querying/api/
+      #   https://www.elastic.co/docs/api/doc/kibana
+      #     WIP: https://github.com/elastic/kibana/issues/137240

docker-compose/technical/swagger/Dockerfile

@@ -0,0 +1,12 @@
+FROM swaggerapi/swagger-ui:latest
+#--start-period=10s --start-interval=5s
+HEALTHCHECK --interval=30s --timeout=10s --retries=3 \
+    CMD wget -Y off -O /dev/null http://localhost:8080/swagger/
+    #CMD curl --fail --noproxy '*' -so /dev/null http://localhost:8080/swagger/
+ENV PORT_IPV6: 8080
+
+#hack for cors
+ENV EMBEDDING: false
+COPY --chmod=0666 ./proxy-cors.conf /etc/nginx/templates/embedding.conf
+
+COPY --chmod=0666 ./swagger-initializer.js /usr/share/nginx/html/swagger-initializer.js

docker-compose/technical/swagger/proxy-cors.conf

@@ -0,0 +1,49 @@
+# Little hack with docker to replace unused embedding.conf to inject additionnal config
+# https://github.com/swagger-api/swagger-ui/blob/master/docker/docker-entrypoint.d/40-swagger-ui.sh
+
+# We add a proxy just to add the missing CORS headers to the servers reponse
+location ~ ^/swagger/proxy-cors/([0-9]+)(.*)$ {
+    set $dest_port $1;
+    set $path $2;
+
+    #[error] 0#0: *1 host.docker.internal could not be resolved (3: Host not found)
+    # set DNS resolver as Docker internal DNS
+    resolver 127.0.0.11 ipv6=off valid=10s;
+    resolver_timeout 5s;
+
+    # prevent dns caching and force nginx to make a dns lookup on each request.
+    #set $target http://host.docker.internal:$dest_port$path;
+    set $target http://172.17.0.1:$dest_port$path;
+    #TODO: why the resolver not work?!
+
+    # Prevent loop requests
+    if ($dest_port = 80) { return 508; }
+    if ($dest_port = 8080) { return 508; }
+    if ($dest_port = 9080) { return 508; }
+
+    # Proxy to the external JSON server
+    # Build the proxy target dynamically based on the extracted port and path
+    proxy_pass $target;
+    #proxy_http_version 1.1;
+    proxy_redirect off;
+
+    # Additional proxy settings (if necessary)
+    proxy_set_header Host $host;
+    proxy_set_header X-Real-IP $remote_addr;
+    proxy_set_header X-Forwarded-Host $server_name;
+    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+    proxy_set_header X-Forwarded-Proto $scheme;
+
+    # Optionally handle timeouts or larger client requests
+    client_max_body_size 10M;
+    proxy_read_timeout 90;
+
+    # Add CORS headers
+    # Note: no need as we are include in a block that already add the headers
+    # https://github.com/swagger-api/swagger-ui/blob/master/docker/default.conf.template
+
+    # Handle preflight OPTIONS requests
+    if ($request_method = OPTIONS) {
+        return 204;  # No Content for preflight
+    }
+}