Skip to content

Commit

Permalink
Host Swagger API documentation with GitHub Pages
Browse files Browse the repository at this point in the history
  • Loading branch information
cb-github-robot authored May 3, 2024
2 parents 2f99669 + 2911ff5 commit 9ce24e0
Show file tree
Hide file tree
Showing 29 changed files with 173 additions and 23 deletions.
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

0 comments on commit 9ce24e0

Please sign in to comment.