| name | update-swagger-ui |
| description | Use when updating the Swagger-UI version in api-docs/ — covers download, rsync, initializer restore, and cleanup of files dropped by upstream |
Update Swagger-UI
A reference/technique skill for syncing a new Swagger-UI dist/ release into api-docs/.
Steps
-
Create a branch
git checkout -b update-swagger-ui-vX.Y.Z
-
Download the release tarball
curl -L "https://api.github.com/repos/swagger-api/swagger-ui/tarball/vX.Y.Z" -o swagger-ui-X.Y.Z.tar.gz
tar xzf swagger-ui-X.Y.Z.tar.gz
The extracted directory is named swagger-api-swagger-ui-<sha>/.
-
Sync dist/ into api-docs/
rsync -av swagger-api-swagger-ui-*/dist/ api-docs/
Use rsync, not cp — cp is aliased with -i in this shell and will prompt interactively for every file.
-
Restore swagger-initializer.js
rsync overwrites it with the upstream default (single url:). Restore the custom multi-URL version from git or from memory — it must contain the urls: [...] array with three entries:
../swagger.json — local file from the repohttps://jonasbn.github.io/gh-pages-swagger-ui-experiment/swagger.json — GitHub Pageshttps://petstore.swagger.io/v2/swagger.json — upstream Petstore
Also ensure layout: "StandaloneLayout" is set (not the default "BaseLayout").
-
Remove files dropped by upstream
Check git status for tracked files that are now missing from the new dist. Use git rm — plain rm is also aliased with -i.
git rm api-docs/<dropped-file>
Example: .map files were dropped in v5.32.8.
-
Commit and open a PR
git add api-docs/
git commit -m "Update Swagger-UI to vX.Y.Z"
git push -u origin update-swagger-ui-vX.Y.Z
gh pr create ...
Common Mistakes
| Mistake | Fix |
|---|
Using cp -r dist/ api-docs/ | Use rsync -av dist/ api-docs/ instead |
Forgetting to restore swagger-initializer.js | Always check it after rsync; upstream uses a single url: key |
| Missing dropped upstream files | Run git status — missing tracked files show as deleted but unstaged |
Using rm to delete tracked files | Use git rm so git stages the deletion |
