trying swagger for UI docs.

Author: RossBugginsNHS

.github/actions/build-sdk/action.yml

@@ -33,6 +33,11 @@ runs:
       shell: bash
       run: mkdir python
 
+    - name: make swagger folder
+      working-directory: ./sdk
+      shell: bash
+      run: mkdir swagger
+
     - name: Build sdks
       working-directory: ./sdk
       shell: bash
@@ -44,6 +49,12 @@ runs:
         path: "sdk/html"
         name: sdk-html-${{ inputs.version }}
 
+    - name: Upload swagger artifact
+      uses: actions/upload-artifact@v4
+      with:
+        path: "sdk/swagger"
+        name: sdk-swagger-${{ inputs.version }}
+
     - name: Upload ts artifact
       uses: actions/upload-artifact@v4
       with:
@@ -68,3 +79,9 @@ runs:
       with:
         path: "sdk/html/"
         name: sdk-html-docs-${{ inputs.version }}
+
+    - name: Upload swagger pages artifact
+      uses: actions/upload-pages-artifact@v3
+      with:
+        path: "sdk/swagger/"
+        name: sdk-swagger-docs-${{ inputs.version }}

.github/workflows/cicd-1-pull-request.yaml

@@ -1,4 +1,4 @@
-name: "1. CI/CD pull request"
+name: "1. CI - Pull Request"
 
 # The total recommended execution time for the "CI/CD Pull Request" workflow is around 20 minutes.
 

.github/workflows/cicd-3-deploy.yaml

@@ -1,4 +1,4 @@
-name: "2. Deploy docs to GitHub Pages"
+name: "2. CD - Deploy"
 
 on:
   workflow_dispatch:
@@ -102,18 +102,18 @@ jobs:
         env:
           GH_TOKEN: ${{ github.token }}
         run: |
-          gh release download ${{steps.get-asset-version.outputs.release_version}} -p sdk-html-docs-*.tar --output artifact.tar
+          gh release download ${{steps.get-asset-version.outputs.release_version}} -p sdk-swagger-docs-*.tar --output artifact.tar
 
       - uses: actions/upload-artifact@v4
         with:
-          name: sdk-html-docs-${{steps.get-asset-version.outputs.release_version}}
+          name: sdk-swagger-docs-${{steps.get-asset-version.outputs.release_version}}
           path: artifact.tar
 
       - name: Deploy to GitHub Pages
         id: deployment
         uses: actions/deploy-pages@v4
         with:
-          artifact_name: sdk-html-docs-${{steps.get-asset-version.outputs.release_version}}
+          artifact_name: sdk-swagger-docs-${{steps.get-asset-version.outputs.release_version}}
 
 
       ### BELOW WAS THE DEFAULT USING THE JEKYLL BUILD

.github/workflows/stage-5-publish.yaml

@@ -82,6 +82,16 @@ jobs:
           asset_name: sdk-html-docs-${{ inputs.version }}.tar
           asset_content_type: "application/gzip"
 
+      - name: "Upload sdk swagger docs release asset"
+        uses: actions/upload-release-asset@v1
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        with:
+          upload_url: "${{ steps.create_release.outputs.upload_url }}"
+          asset_path: ./artifacts/sdk-swagger-docs-${{ inputs.version }}/artifact.tar
+          asset_name: sdk-swagger-docs-${{ inputs.version }}.tar
+          asset_content_type: "application/gzip"
+
       #- name: "tar gz jekyll docs release asset"
       #   # Git hub pages needs a single tar called artifact inside the zip.
       #  working-directory: ./artifacts/jekyll-docs-${{ inputs.version }}

Makefile

@@ -27,6 +27,8 @@ clean:: # Clean-up project resources (main) @Operations
 serve:
 	npm run serve
 
+serve-swagger:
+	npm run serve-swagger-docs
 
 config:: _install-dependencies version # Configure development environment (main) @Configuration
 	npm install

package.json

@@ -55,6 +55,7 @@
     "lint:fix": "npm run lint:fix --workspaces",
     "serve": "npm run serve-html-docs",
     "serve-html-docs": "npx serve sdk/html -p 3050",
+    "serve-swagger-docs": "npx serve sdk/swagger -p 3051",
     "start": "npm run start --workspace frontend",
     "test:unit": "npm run test:unit --workspaces",
     "typecheck": "npm run typecheck --workspaces"

sdk/Makefile

@@ -4,6 +4,7 @@ SHELL = /bin/bash
 
 build: version # Build the project artefact @Pipeline
 	cd .. && npm run build && cd sdk
+	./swagger-static.sh
 
 clean: # Clean-up project resources (main) @Operations
 	rm -rf */

sdk/_config.version.yml

@@ -1 +1 @@
-version: 0.0.1-20250703.074729+c9e6134
+version: 0.0.1-20250703.100841+c9f3336

sdk/swagger-initializer.js

@@ -0,0 +1,20 @@
+window.onload = function() {
+  //<editor-fold desc="Changeable Configuration Block">
+
+  // the following lines will be replaced by docker/configurator, when it runs in a docker-container
+  window.ui = SwaggerUIBundle({
+    url: "swagger.json",
+    dom_id: '#swagger-ui',
+    deepLinking: true,
+    presets: [
+      SwaggerUIBundle.presets.apis,
+      SwaggerUIStandalonePreset
+    ],
+    plugins: [
+      SwaggerUIBundle.plugins.DownloadUrl
+    ],
+    layout: "StandaloneLayout"
+  });
+
+  //</editor-fold>
+};

sdk/swagger-static.sh

@@ -0,0 +1,13 @@
+#! /bin/sh
+
+VERSION=5.26.0
+wget https://github.com/swagger-api/swagger-ui/archive/refs/tags/v$VERSION.zip -O swagger.zip
+mkdir -p swagger
+rm -r swagger/*
+
+unzip swagger.zip "swagger-ui-$VERSION/dist/*" -d swagger
+mv swagger/swagger-ui-$VERSION/dist/* swagger
+rm -r swagger/swagger-ui-$VERSION
+cp swagger-initializer.js swagger/swagger-initializer.js
+cp ../specification/api/notify-supplier.yml swagger/swagger.json
+rm swagger.zip