feat: OpenApi schema (#171)

README.md

@@ -126,6 +126,12 @@ This project follows the [all-contributors](https://allcontributors.org/docs/en/
 
 :warning: for contributions on schemas, please see [Versions README](gbfs-validator/versions/README.md)
 
-## Acknowledgements
+## OpenAPI Specification
+
+:warning: **Subject to change**: This OpenAPI specification may change at any time. We do not recommend building any production systems that depend on this API directly.
+
+The OpenAPI specification can be viewed at: https://mobilitydata.github.io/gbfs-validator/SwaggerUI/index.html.
+
+## Acknowledgments
 
 This project was originally created by Pierrick Paul ([@PierrickP](https://github.com/PierrickP)) at [fluctuo](https://fluctuo.com/) - MobilityData started maintaining the project in September 2021.

common/http-utils.js

@@ -0,0 +1,38 @@
+/**
+ * HTTP Headers to be used on OPTIONS requests and responses
+ */
+const corsHeaders = {
+  'Access-Control-Allow-Origin': '*',
+  'Access-Control-Allow-Methods': 'GET, POST, OPTIONS',
+  'Access-Control-Allow-Headers': '*',
+  'Access-Control-Request-Headers': '*'
+}
+
+/**
+ * Default application response headers
+ */
+const defaultApplicationResponseHeaders = {
+  ...corsHeaders,
+  'Content-Type': 'application/json'
+}
+
+/**
+ * 
+ * @param event associated with the HTTP request. Example: GET, OPTIONS
+ * @returns the CORS response for event equal OPTIONS, undefined otherwise
+ */
+const getCorsResponse = (event) => {
+  if (event.httpMethod === 'OPTIONS') {
+    return {
+      statusCode: 200,
+      headers: corsHeaders
+    }
+  }
+  return undefined
+}
+
+module.exports = {
+  corsHeaders,
+  defaultApplicationResponseHeaders,
+  getCorsResponse,
+}

docs/SwaggerUI/README.md

@@ -0,0 +1,58 @@
+# How to host Swagger API documentation with GitHub Pages
+[<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/)
+
+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.
+
+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).
+
+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/).
+
+## Steps to use this template
+
+1. Click the `Use this template` button above to create a new repository from this template.
+
+2. Go to the settings for your repository at `https://github.com/{github-username}/{repository-name}/settings` and enable GitHub Pages.
+
+    ![Headers](/screenshots/swagger-github-pages.png?raw=true)
+
+3. Browse to the Swagger documentation at `https://{github-username}.github.io/{repository-name}/`.
+
+
+## Steps to manually configure in your own repository
+
+1. Download the latest stable release of the Swagger UI [here](https://github.com/swagger-api/swagger-ui/releases).
+
+2. Extract the contents and copy the "dist" directory to the root of your repository.
+
+3. Move the file "index.html" from the directory "dist" to the root of your repository.
+    ```
+    mv dist/index.html .
+    ```
+    
+4. Copy the YAML specification file for your API to the root of your repository.
+
+5. Edit [dist/swagger-initializer.js](dist/swagger-initializer.js) and change the `url` property to reference your local YAML file. 
+    ```javascript
+        window.ui = SwaggerUIBundle({
+            url: "swagger.yaml",
+        ...
+    ```
+    Then fix any references to files in the "dist" directory.
+    ```html
+    ...
+    <link rel="stylesheet" type="text/css" href="dist/swagger-ui.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" />    
+    ...
+    <script src="dist/swagger-ui-bundle.js"> </script>
+    <script src="dist/swagger-ui-standalone-preset.js"> </script>    
+    ...
+    ```
+    
+6. Go to the settings for your repository at `https://github.com/{github-username}/{repository-name}/settings` and enable GitHub Pages.
+
+    ![Headers](/screenshots/swagger-github-pages.png?raw=true)
+    
+7. Browse to the Swagger documentation at `https://{github-username}.github.io/{repository-name}/`.
+
+   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/).

docs/SwaggerUI/dist/index.css

@@ -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;
+}

docs/SwaggerUI/dist/oauth2-redirect.html

@@ -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>

docs/SwaggerUI/dist/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: "../gbfs-validator.yaml",
+    dom_id: '#swagger-ui',
+    deepLinking: true,
+    presets: [
+      SwaggerUIBundle.presets.apis,
+      SwaggerUIStandalonePreset
+    ],
+    plugins: [
+      SwaggerUIBundle.plugins.DownloadUrl
+    ],
+    layout: "StandaloneLayout"
+  });
+
+  //</editor-fold>
+};

docs/SwaggerUI/index.html

@@ -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>

docs/SwaggerUI/swagger-ui.version

@@ -0,0 +1 @@
+v4.19.0