Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Host Swagger API documentation with GitHub Pages #80

Merged
merged 2 commits into from
May 3, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion Dockerfile
Original file line number Diff line number Diff line change
Expand Up @@ -37,6 +37,7 @@ COPY --from=builder /go/src/github.com/cloud-barista/cm-beetle/scripts/ /app/scr
# COPY --from=builder /go/src/github.com/cloud-barista/cm-beetle/conf/ /app/conf/

COPY --from=builder /go/src/github.com/cloud-barista/cm-beetle/cmd/cm-beetle /app/
COPY --from=builder /go/src/github.com/cloud-barista/cm-beetle/api/ /app/api/

## Set system endpoints
ENV CMBEETLE_ROOT /app
Expand Down Expand Up @@ -82,7 +83,7 @@ ENV SELF_ENDPOINT localhost:8056

## Environment variables that you don't need to touch
# Swagger UI API document file path
ENV APIDOC_PATH /app/pkg/api/rest/docs/swagger.json
ENV APIDOC_PATH /app/api/swagger.json

ENTRYPOINT [ "/app/cm-beetle" ]

Expand Down
4 changes: 2 additions & 2 deletions pkg/api/rest/docs/docs.go → api/docs.go
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
// Package docs Code generated by swaggo/swag. DO NOT EDIT
package docs
// Package api Code generated by swaggo/swag. DO NOT EDIT
package api

import "github.com/swaggo/swag"

Expand Down
File renamed without changes.
File renamed without changes.
10 changes: 5 additions & 5 deletions conf/config.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@ cbtumblebug:

## Logger configuration
logfile:
# Set log file path (default logfile path: ./cm-beetle.log)
# Set log file path (default logfile path: ./cm-beetle.log)
path: ./cm-beetle.log
maxsize: 10
maxbackups: 3
Expand Down Expand Up @@ -49,11 +49,11 @@ api:
# Set API_ALLOW_ORIGINS (ex: https://cloud-barista.org,http://localhost:8080 or * for all)
allow:
origins: "*"

# Set API_AUTH_ENABLED=true currently for basic auth for all routes (i.e., url or path)
auth:
enabled: true

username: default
password: default

Expand All @@ -66,7 +66,7 @@ self:
endpoint: localhost:8056

## Environment variables that you don't need to touch
# Swagger UI API document file path
# Swagger UI API document file path
apidoc:
# export APIDOC_PATH=$CMBEETLE_ROOT/src/api/rest/docs/swagger.json
# export APIDOC_PATH=$CMBEETLE_ROOT/api/swagger.json
path: # To be set in runtime (based on cmbeetle.root)
2 changes: 1 addition & 1 deletion conf/setup.env
Original file line number Diff line number Diff line change
Expand Up @@ -45,4 +45,4 @@ export SELF_ENDPOINT=localhost:8056

## Environment variables that you don't need to touch
# Swagger UI API document file path
export APIDOC_PATH=$CMBEETLE_ROOT/src/api/rest/docs/swagger.json
export APIDOC_PATH=$CMBEETLE_ROOT/api/swagger.json
10 changes: 5 additions & 5 deletions conf/template-config.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@ cbtumblebug:

## Logger configuration
logfile:
# Set log file path (default logfile path: ./cm-beetle.log)
# Set log file path (default logfile path: ./cm-beetle.log)
path: ./cm-beetle.log
maxsize: 10
maxbackups: 3
Expand Down Expand Up @@ -49,11 +49,11 @@ api:
# Set API_ALLOW_ORIGINS (ex: https://cloud-barista.org,http://localhost:8080 or * for all)
allow:
origins: "*"

# Set API_AUTH_ENABLED=true currently for basic auth for all routes (i.e., url or path)
auth:
enabled: true

username: default
password: default

Expand All @@ -66,7 +66,7 @@ self:
endpoint: localhost:8056

## Environment variables that you don't need to touch
# Swagger UI API document file path
# Swagger UI API document file path
apidoc:
# export APIDOC_PATH=$CMBEETLE_ROOT/src/api/rest/docs/swagger.json
# export APIDOC_PATH=$CMBEETLE_ROOT/api/swagger.json
path: # To be set in runtime (based on cmbeetle.root)
2 changes: 1 addition & 1 deletion conf/template-setup.env
Original file line number Diff line number Diff line change
Expand Up @@ -45,4 +45,4 @@ export SELF_ENDPOINT=localhost:8056

## Environment variables that you don't need to touch
# Swagger UI API document file path
export APIDOC_PATH=$CMBEETLE_ROOT/src/api/rest/docs/swagger.json
export APIDOC_PATH=$CMBEETLE_ROOT/api/swagger.json
Binary file added dist/favicon-16x16.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added dist/favicon-32x32.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
16 changes: 16 additions & 0 deletions dist/index.css
Original file line number Diff line number Diff line change
@@ -0,0 +1,16 @@
html {
box-sizing: border-box;
overflow: -moz-scrollbars-vertical;
overflow-y: scroll;
}

*,
*:before,
*:after {
box-sizing: inherit;
}

body {
margin: 0;
background: #fafafa;
}
79 changes: 79 additions & 0 deletions dist/oauth2-redirect.html
Original file line number Diff line number Diff line change
@@ -0,0 +1,79 @@
<!doctype html>
<html lang="en-US">
<head>
<title>Swagger UI: OAuth2 Redirect</title>
</head>
<body>
<script>
'use strict';
function run () {
var oauth2 = window.opener.swaggerUIRedirectOauth2;
var sentState = oauth2.state;
var redirectUrl = oauth2.redirectUrl;
var isValid, qp, arr;

if (/code|token|error/.test(window.location.hash)) {
qp = window.location.hash.substring(1).replace('?', '&');
} else {
qp = location.search.substring(1);
}

arr = qp.split("&");
arr.forEach(function (v,i,_arr) { _arr[i] = '"' + v.replace('=', '":"') + '"';});
qp = qp ? JSON.parse('{' + arr.join() + '}',
function (key, value) {
return key === "" ? value : decodeURIComponent(value);
}
) : {};

isValid = qp.state === sentState;

if ((
oauth2.auth.schema.get("flow") === "accessCode" ||
oauth2.auth.schema.get("flow") === "authorizationCode" ||
oauth2.auth.schema.get("flow") === "authorization_code"
) && !oauth2.auth.code) {
if (!isValid) {
oauth2.errCb({
authId: oauth2.auth.name,
source: "auth",
level: "warning",
message: "Authorization may be unsafe, passed state was changed in server. The passed state wasn't returned from auth server."
});
}

if (qp.code) {
delete oauth2.state;
oauth2.auth.code = qp.code;
oauth2.callback({auth: oauth2.auth, redirectUrl: redirectUrl});
} else {
let oauthErrorMsg;
if (qp.error) {
oauthErrorMsg = "["+qp.error+"]: " +
(qp.error_description ? qp.error_description+ ". " : "no accessCode received from the server. ") +
(qp.error_uri ? "More info: "+qp.error_uri : "");
}

oauth2.errCb({
authId: oauth2.auth.name,
source: "auth",
level: "error",
message: oauthErrorMsg || "[Authorization failed]: no accessCode received from the server."
});
}
} else {
oauth2.callback({auth: oauth2.auth, token: qp, isValid: isValid, redirectUrl: redirectUrl});
}
window.close();
}

if (document.readyState !== 'loading') {
run();
} else {
document.addEventListener('DOMContentLoaded', function () {
run();
});
}
</script>
</body>
</html>
20 changes: 20 additions & 0 deletions dist/swagger-initializer.js
Original file line number Diff line number Diff line change
@@ -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: "../api/swagger.yaml",
dom_id: '#swagger-ui',
deepLinking: true,
presets: [
SwaggerUIBundle.presets.apis,
SwaggerUIStandalonePreset
],
plugins: [
SwaggerUIBundle.plugins.DownloadUrl
],
layout: "StandaloneLayout"
});

//</editor-fold>
};
2 changes: 2 additions & 0 deletions dist/swagger-ui-bundle.js

Large diffs are not rendered by default.

1 change: 1 addition & 0 deletions dist/swagger-ui-bundle.js.map

Large diffs are not rendered by default.

3 changes: 3 additions & 0 deletions dist/swagger-ui-es-bundle-core.js

Large diffs are not rendered by default.

1 change: 1 addition & 0 deletions dist/swagger-ui-es-bundle-core.js.map

Large diffs are not rendered by default.

2 changes: 2 additions & 0 deletions dist/swagger-ui-es-bundle.js

Large diffs are not rendered by default.

1 change: 1 addition & 0 deletions dist/swagger-ui-es-bundle.js.map

Large diffs are not rendered by default.

2 changes: 2 additions & 0 deletions dist/swagger-ui-standalone-preset.js

Large diffs are not rendered by default.

1 change: 1 addition & 0 deletions dist/swagger-ui-standalone-preset.js.map

Large diffs are not rendered by default.

3 changes: 3 additions & 0 deletions dist/swagger-ui.css

Large diffs are not rendered by default.

1 change: 1 addition & 0 deletions dist/swagger-ui.css.map

Large diffs are not rendered by default.

2 changes: 2 additions & 0 deletions dist/swagger-ui.js

Large diffs are not rendered by default.

1 change: 1 addition & 0 deletions dist/swagger-ui.js.map

Large diffs are not rendered by default.

7 changes: 1 addition & 6 deletions go.work.sum
Original file line number Diff line number Diff line change
Expand Up @@ -114,25 +114,20 @@ go.uber.org/zap v1.23.0 h1:OjGQ5KQDEUawVHxNwQgPpiypGHOxo2mNZsOqTak4fFY=
go.uber.org/zap v1.23.0/go.mod h1:D+nX8jyLsMHMYrln8A0rJjFt/T/9/bGgIhAqxv5URuY=
golang.org/x/crypto v0.13.0 h1:mvySKfSWJ+UKUii46M40LOvyWfN0s2U+46/jDd0e6Ck=
golang.org/x/crypto v0.13.0/go.mod h1:y6Z2r+Rw4iayiXXAIxJIDAJ1zMW4yaTpebo8fPOliYc=
golang.org/x/crypto v0.22.0 h1:g1v0xeRhjcugydODzvb3mEM9SQ0HGp9s/nh3COQ/C30=
golang.org/x/crypto v0.22.0/go.mod h1:vr6Su+7cTlO45qkww3VDJlzDn0ctJvRgYbC2NvXHt+M=
golang.org/x/mod v0.9.0/go.mod h1:iBbtSCu2XBx23ZKBPSOrRkjjQPZFPuis4dIYUhu/chs=
golang.org/x/net v0.0.0-20200520004742-59133d7f0dd7/go.mod h1:qpuaurCH72eLCgpAm/N6yyVIVM9cpaDIP3A8BGJEC5A=
golang.org/x/net v0.8.0/go.mod h1:QVkue5JL9kW//ek3r6jTKnTFis1tRmNAW2P1shuFdJc=
golang.org/x/net v0.24.0 h1:1PcaxkF854Fu3+lvBIx5SYn9wRlBzzcnHZSiaFFAb0w=
golang.org/x/net v0.24.0/go.mod h1:2Q7sJY5mzlzWjKtYUEXSlBWCdyaioyXzRB2RtU8KVE8=
golang.org/x/oauth2 v0.7.0/go.mod h1:hPLQkd9LyjfXTiRohC/41GhcFqxisoUQ99sCUOHO9x4=
golang.org/x/sync v0.5.0/go.mod h1:Czt+wKu1gCyEFDUtn0jG5QVvpJ6rzVqr5aXyt9drQfk=
golang.org/x/sys v0.0.0-20190904154756-749cb33beabd/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
golang.org/x/sys v0.0.0-20191005200804-aed5e4c7ecf9/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
golang.org/x/sys v0.0.0-20191120155948-bd437916bb0e/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
golang.org/x/sys v0.0.0-20200519105757-fe76b779f299/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
golang.org/x/sys v0.12.0 h1:CM0HF96J0hcLAwsHPJZjfdNzs0gftsLfgKt57wWHJ0o=
golang.org/x/sys v0.19.0 h1:q5f1RH2jigJ1MoAWp2KTp3gm5zAGFUTarQZ5U386+4o=
golang.org/x/sys v0.19.0/go.mod h1:/VUhepiaJMQUp4+oa/7Zr1D23ma6VTLIYjOOTFZPUcA=
golang.org/x/term v0.10.0/go.mod h1:lpqdcUyK/oCiQxvxVrppt5ggO2KCZ5QblwqPnfZ6d5o=
golang.org/x/term v0.12.0/go.mod h1:owVbMEjm3cBLCHdkQu9b1opXd4ETQWc3BhuQGKgXgvU=
golang.org/x/term v0.15.0/go.mod h1:BDl952bC7+uMoWR75FIrCDx79TPU9oHkTZ9yRbYOrX0=
golang.org/x/term v0.19.0/go.mod h1:2CuTdWZ7KHSQwUzKva0cbMg6q2DMI3Mmxp+gKJbskEk=
golang.org/x/xerrors v0.0.0-20231012003039-104605ab7028/go.mod h1:NDW/Ps6MPRej6fsCIbMTohpP40sJ/P/vI1MoTEGwX90=
google.golang.org/api v0.122.0/go.mod h1:gcitW0lvnyWjSp9nKxAbdHKIZ6vF4aajGueeslZOyms=
google.golang.org/genproto v0.0.0-20230410155749-daa745c078e1 h1:KpwkzHKEF7B9Zxg18WzOa7djJ+Ha5DzthMyZYQfEn2A=
Expand Down
19 changes: 19 additions & 0 deletions index.html
Original file line number Diff line number Diff line change
@@ -0,0 +1,19 @@
<!-- HTML for static distribution bundle build -->
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>Swagger UI</title>
<link rel="stylesheet" type="text/css" href="dist/swagger-ui.css" />
<link rel="stylesheet" type="text/css" href="dist/index.css" />
<link rel="icon" type="image/png" href="dist/favicon-32x32.png" sizes="32x32" />
<link rel="icon" type="image/png" href="dist/favicon-16x16.png" sizes="16x16" />
</head>

<body>
<div id="swagger-ui"></div>
<script src="dist/swagger-ui-bundle.js" charset="UTF-8"> </script>
<script src="dist/swagger-ui-standalone-preset.js" charset="UTF-8"> </script>
<script src="dist/swagger-initializer.js" charset="UTF-8"> </script>
</body>
</html>
2 changes: 1 addition & 1 deletion pkg/Makefile
Original file line number Diff line number Diff line change
@@ -1,2 +1,2 @@
swag swagger:
~/go/bin/swag i -g ./api/rest/server/server.go -o ./api/rest/docs
~/go/bin/swag i -g ./api/rest/server/server.go -o ../api
2 changes: 1 addition & 1 deletion pkg/api/rest/server/server.go
Original file line number Diff line number Diff line change
Expand Up @@ -37,7 +37,7 @@ import (
"github.com/labstack/echo/v4/middleware"

// echo-swagger middleware
_ "github.com/cloud-barista/cm-beetle/pkg/api/rest/docs"
_ "github.com/cloud-barista/cm-beetle/api"
echoSwagger "github.com/swaggo/echo-swagger"

// Black import (_) is for running a package's init() function without using its other contents.
Expand Down