Skip to content

Commit a68ed81

Browse files
octfxoctfx
committed
Initial commit
0 parents  commit a68ed81

23 files changed

+987
-0
lines changed

‎.github/workflows/update-swagger.yml

+52
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
name: Update Swagger UI
2+
on:
3+
schedule:
4+
- cron: '0 10 * * *'
5+
workflow_dispatch:
6+
7+
jobs:
8+
updateSwagger:
9+
runs-on: ubuntu-latest
10+
steps:
11+
- uses: actions/checkout@v2
12+
- name: Get Latest Swagger UI Release
13+
id: swagger-ui
14+
run: |
15+
echo ::set-output name=release_tag::$(curl -sL https://api.github.com/repos/swagger-api/swagger-ui/releases/latest | jq -r ".tag_name")
16+
echo ::set-output name=current_tag::$(<swagger-ui.version)
17+
- name: Update Swagger UI
18+
if: steps.swagger-ui.outputs.current_tag != steps.swagger-ui.outputs.release_tag
19+
env:
20+
RELEASE_TAG: ${{ steps.swagger-ui.outputs.release_tag }}
21+
SWAGGER_YAML: "swagger.yaml"
22+
run: |
23+
# Delete the dist directory and index.html
24+
rm -fr dist index.html
25+
# Download the release
26+
curl -sL -o $RELEASE_TAG https://api.github.com/repos/swagger-api/swagger-ui/tarball/$RELEASE_TAG
27+
# Extract the dist directory
28+
tar -xzf $RELEASE_TAG --strip-components=1 $(tar -tzf $RELEASE_TAG | head -1 | cut -f1 -d"/")/dist
29+
rm $RELEASE_TAG
30+
# Move index.html to the root
31+
mv dist/index.html .
32+
# Fix references in index.html
33+
sed -i "s|https://petstore.swagger.io/v2/swagger.json|$SWAGGER_YAML|g" index.html
34+
sed -i "s|href=\"./|href=\"dist/|g" index.html
35+
sed -i "s|src=\"./|src=\"dist/|g" index.html
36+
sed -i "s|href=\"index|href=\"dist/index|g" index.html
37+
# Update current release
38+
echo ${{ steps.swagger-ui.outputs.release_tag }} > swagger-ui.version
39+
- name: Create Pull Request
40+
uses: peter-evans/create-pull-request@v3
41+
with:
42+
commit-message: Update swagger-ui to ${{ steps.swagger-ui.outputs.release_tag }}
43+
title: Update SwaggerUI to ${{ steps.swagger-ui.outputs.release_tag }}
44+
body: |
45+
Updates [swagger-ui][1] to ${{ steps.swagger-ui.outputs.release_tag }}
46+
47+
Auto-generated by [create-pull-request][2]
48+
49+
[1]: https://github.com/swagger-api/swagger-ui
50+
[2]: https://github.com/peter-evans/create-pull-request
51+
labels: dependencies, automated pr
52+
branch: swagger-ui-updates

‎README.md

+58
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
# How to host Swagger API documentation with GitHub Pages
2+
[<img alt="The blog of Peter Evans: How to Host Swagger Documentation With Github Pages" title="View blog post" src="https://peterevans.dev/img/blog-published-badge.svg">](https://peterevans.dev/posts/how-to-host-swagger-docs-with-github-pages/)
3+
4+
This repository is a template for using the [Swagger UI](https://github.com/swagger-api/swagger-ui) to dynamically generate beautiful documentation for your API and host it for free with GitHub Pages.
5+
6+
The template will periodically auto-update the Swagger UI dependency and create a pull request. See the [GitHub Actions workflow here](.github/workflows/update-swagger.yml).
7+
8+
The example API specification used by this repository can be seen hosted at [https://peter-evans.github.io/swagger-github-pages](https://peter-evans.github.io/swagger-github-pages/).
9+
10+
## Steps to use this template
11+
12+
1. Click the `Use this template` button above to create a new repository from this template.
13+
14+
2. Go to the settings for your repository at `https://github.com/{github-username}/{repository-name}/settings` and enable GitHub Pages.
15+
16+
![Headers](/screenshots/swagger-github-pages.png?raw=true)
17+
18+
3. Browse to the Swagger documentation at `https://{github-username}.github.io/{repository-name}/`.
19+
20+
21+
## Steps to manually configure in your own repository
22+
23+
1. Download the latest stable release of the Swagger UI [here](https://github.com/swagger-api/swagger-ui/releases).
24+
25+
2. Extract the contents and copy the "dist" directory to the root of your repository.
26+
27+
3. Move the file "index.html" from the directory "dist" to the root of your repository.
28+
```
29+
mv dist/index.html .
30+
```
31+
32+
4. Copy the YAML specification file for your API to the root of your repository.
33+
34+
5. Edit [index.html](index.html) and change the `url` property to reference your local YAML file.
35+
```javascript
36+
const ui = SwaggerUIBundle({
37+
url: "swagger.yaml",
38+
...
39+
```
40+
Then fix any references to files in the "dist" directory.
41+
```html
42+
...
43+
<link rel="stylesheet" type="text/css" href="dist/swagger-ui.css" >
44+
<link rel="icon" type="image/png" href="dist/favicon-32x32.png" sizes="32x32" />
45+
<link rel="icon" type="image/png" href="dist/favicon-16x16.png" sizes="16x16" />
46+
...
47+
<script src="dist/swagger-ui-bundle.js"> </script>
48+
<script src="dist/swagger-ui-standalone-preset.js"> </script>
49+
...
50+
```
51+
52+
6. Go to the settings for your repository at `https://github.com/{github-username}/{repository-name}/settings` and enable GitHub Pages.
53+
54+
![Headers](/screenshots/swagger-github-pages.png?raw=true)
55+
56+
7. Browse to the Swagger documentation at `https://{github-username}.github.io/{repository-name}/`.
57+
58+
The example API specification used by this repository can be seen hosted at [https://peter-evans.github.io/swagger-github-pages](https://peter-evans.github.io/swagger-github-pages/).

‎dist/favicon-16x16.png

665 Bytes
Loading

‎dist/favicon-32x32.png

628 Bytes
Loading

‎dist/index.css

+16
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
html {
2+
box-sizing: border-box;
3+
overflow: -moz-scrollbars-vertical;
4+
overflow-y: scroll;
5+
}
6+
7+
*,
8+
*:before,
9+
*:after {
10+
box-sizing: inherit;
11+
}
12+
13+
body {
14+
margin: 0;
15+
background: #fafafa;
16+
}

‎dist/oauth2-redirect.html

+79
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
<!doctype html>
2+
<html lang="en-US">
3+
<head>
4+
<title>Swagger UI: OAuth2 Redirect</title>
5+
</head>
6+
<body>
7+
<script>
8+
'use strict';
9+
function run () {
10+
var oauth2 = window.opener.swaggerUIRedirectOauth2;
11+
var sentState = oauth2.state;
12+
var redirectUrl = oauth2.redirectUrl;
13+
var isValid, qp, arr;
14+
15+
if (/code|token|error/.test(window.location.hash)) {
16+
qp = window.location.hash.substring(1);
17+
} else {
18+
qp = location.search.substring(1);
19+
}
20+
21+
arr = qp.split("&");
22+
arr.forEach(function (v,i,_arr) { _arr[i] = '"' + v.replace('=', '":"') + '"';});
23+
qp = qp ? JSON.parse('{' + arr.join() + '}',
24+
function (key, value) {
25+
return key === "" ? value : decodeURIComponent(value);
26+
}
27+
) : {};
28+
29+
isValid = qp.state === sentState;
30+
31+
if ((
32+
oauth2.auth.schema.get("flow") === "accessCode" ||
33+
oauth2.auth.schema.get("flow") === "authorizationCode" ||
34+
oauth2.auth.schema.get("flow") === "authorization_code"
35+
) && !oauth2.auth.code) {
36+
if (!isValid) {
37+
oauth2.errCb({
38+
authId: oauth2.auth.name,
39+
source: "auth",
40+
level: "warning",
41+
message: "Authorization may be unsafe, passed state was changed in server Passed state wasn't returned from auth server"
42+
});
43+
}
44+
45+
if (qp.code) {
46+
delete oauth2.state;
47+
oauth2.auth.code = qp.code;
48+
oauth2.callback({auth: oauth2.auth, redirectUrl: redirectUrl});
49+
} else {
50+
let oauthErrorMsg;
51+
if (qp.error) {
52+
oauthErrorMsg = "["+qp.error+"]: " +
53+
(qp.error_description ? qp.error_description+ ". " : "no accessCode received from the server. ") +
54+
(qp.error_uri ? "More info: "+qp.error_uri : "");
55+
}
56+
57+
oauth2.errCb({
58+
authId: oauth2.auth.name,
59+
source: "auth",
60+
level: "error",
61+
message: oauthErrorMsg || "[Authorization failed]: no accessCode received from the server"
62+
});
63+
}
64+
} else {
65+
oauth2.callback({auth: oauth2.auth, token: qp, isValid: isValid, redirectUrl: redirectUrl});
66+
}
67+
window.close();
68+
}
69+
70+
if (document.readyState !== 'loading') {
71+
run();
72+
} else {
73+
document.addEventListener('DOMContentLoaded', function () {
74+
run();
75+
});
76+
}
77+
</script>
78+
</body>
79+
</html>

‎dist/swagger-initializer.js

+20
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
window.onload = function() {
2+
//<editor-fold desc="Changeable Configuration Block">
3+
4+
// the following lines will be replaced by docker/configurator, when it runs in a docker-container
5+
window.ui = SwaggerUIBundle({
6+
url: "https://petstore.swagger.io/v2/swagger.json",
7+
dom_id: '#swagger-ui',
8+
deepLinking: true,
9+
presets: [
10+
SwaggerUIBundle.presets.apis,
11+
SwaggerUIStandalonePreset
12+
],
13+
plugins: [
14+
SwaggerUIBundle.plugins.DownloadUrl
15+
],
16+
layout: "StandaloneLayout"
17+
});
18+
19+
//</editor-fold>
20+
};

‎dist/swagger-ui-bundle.js

+3
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎dist/swagger-ui-bundle.js.map

+1
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎dist/swagger-ui-es-bundle-core.js

+3
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎dist/swagger-ui-es-bundle-core.js.map

+1
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎dist/swagger-ui-es-bundle.js

+3
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎dist/swagger-ui-es-bundle.js.map

+1
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎dist/swagger-ui-standalone-preset.js

+3
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎dist/swagger-ui-standalone-preset.js.map

+1
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎dist/swagger-ui.css

+4
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎dist/swagger-ui.css.map

+1
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎dist/swagger-ui.js

+2
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎dist/swagger-ui.js.map

+1
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎index.html

+19
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
<!-- HTML for static distribution bundle build -->
2+
<!DOCTYPE html>
3+
<html lang="en">
4+
<head>
5+
<meta charset="UTF-8">
6+
<title>Swagger UI</title>
7+
<link rel="stylesheet" type="text/css" href="dist/swagger-ui.css" />
8+
<link rel="stylesheet" type="text/css" href="dist/index.css" />
9+
<link rel="icon" type="image/png" href="dist/favicon-32x32.png" sizes="32x32" />
10+
<link rel="icon" type="image/png" href="dist/favicon-16x16.png" sizes="16x16" />
11+
</head>
12+
13+
<body>
14+
<div id="swagger-ui"></div>
15+
<script src="dist/swagger-ui-bundle.js" charset="UTF-8"> </script>
16+
<script src="dist/swagger-ui-standalone-preset.js" charset="UTF-8"> </script>
17+
<script src="dist/swagger-initializer.js" charset="UTF-8"> </script>
18+
</body>
19+
</html>

‎screenshots/swagger-github-pages.png

14.4 KB
Loading

‎swagger-ui.version

+1
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
v4.12.0

0 commit comments

Comments
 (0)