Add Swagger

api.yaml

@@ -0,0 +1,249 @@
+openapi: 3.0.1
+info:
+  title: GreekSchools Open Access Data Service API
+  version: 0.0.1
+servers:
+  - url: https://6012.greekschools.eu/api/{basePath} # TODO: check
+    variables:
+      basePath:
+        default: v1
+security:
+  - bearerAuth: []
+paths:
+  /latest:
+    get:
+      tags:
+      - versions
+      summary: Get the latest available published version
+      responses:
+        "200":
+          description: The latest version
+          content:
+            application/json:
+              schema:
+                type: string
+        "404":
+          description: Not Found
+        "500":
+          description: Internal Server Error
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/error"
+
+  /versions:
+    get:
+      tags:
+      - versions
+      summary: Get the list of available published units versions
+      responses:
+        "200":
+          description: The list of available versions
+          content:
+            application/json:
+              schema:
+                type: array
+                items: 
+                  type: string
+        "500":
+          description: Internal Server Error
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/error"
+  /units: # TODO
+    get:
+      tags:
+      - units
+      summary: Get the list of published units of the project
+      parameters:
+        - name: v
+          in: query
+          example: 20230623
+          schema:
+            type: string
+        - name: target
+          in: query
+          example: xxxx-yyyy-tttt-zzzz
+          schema:
+            type: string
+        - name: offset
+          in: query
+          example: 0
+          schema:
+            type: integer
+        - name: limit
+          in: query
+          example: 10
+          schema:
+            type: integer
+
+      responses:
+        "200":
+          description: get all the working units
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  data:
+                    type: array
+                    items:
+                      $ref: "#/components/schemas/unit"
+                  links:
+                    $ref: "#/components/schemas/links"
+                  count:
+                    type: integer
+        "500":
+          description: Internal Server Error
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/error"
+  /units/{id}: # TODO
+    parameters:
+      - name: v
+        in: query
+        example: 20230623
+        schema:
+          type: string
+      - name: id
+        in: path
+        required: true
+        schema:
+          type: string
+    get:
+      tags:
+        - units
+      responses:
+        "200":
+          description: get the unit
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/unit"
+        "404":
+          description: Not Found
+        "500":
+          description: Internal Server Error
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/error"
+  /status:
+    get:
+      responses:
+        "200":
+          description: OK
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/status"
+components:
+  schemas:
+      # TODO: define error structure to be returned on 500
+      idObj:
+        type: object
+        required:
+          - id
+        properties:
+          id:
+            type: string
+            format: uuid
+      error:
+        type: object
+        properties:
+            timestamp:
+              type: string
+              format: date-time
+            message:
+              type: string
+            path:
+              type: string
+              example: /api/v1/units/
+      unitRequest:
+        type: object
+        required:
+          - title
+          - children
+          - createdAt
+        properties:
+          createdAt:
+            type: string
+          title:
+            type: string
+          target: 
+            type: string
+            format: uuid
+          metadata:
+            type: array
+            items:
+              $ref: "#/components/schemas/unit" # TODO: check is this should be a string array
+          children: 
+            type: array
+            items:
+              type: string
+              format: uuid
+          ranges:
+            type: array
+            items:
+              $ref: "#/components/schemas/range"
+          creator: 
+            type: string
+            description: User id and name/label of the creator
+          dsl:
+            $ref: "#/components/schemas/dsl"
+            description: When undefined this is a container unit
+      unit:
+        allOf:
+          - $ref: "#/components/schemas/idObj"
+          - $ref: "#/components/schemas/unitRequest" 
+      range:
+        type: object
+        properties:
+          lineStart:
+            type: number
+          lineEnd:
+            type: number
+          colStart:
+            type: number
+          colEnd:
+            type: number 
+      dsl:
+        type: object
+        required:
+          - content
+          - language
+        properties:
+          content:
+            type: string
+            description: The code in the chosen language
+          language:
+            type: string
+            description: The dsl language id
+            example: gs-lit-app
+      links:
+        type: object
+        properties:
+          self:
+            type: string
+          prev:
+            type: string
+          next:
+            type: string
+          last:
+            type: string
+          first:
+            type: string
+      status:
+        type: object
+        required:
+          - status
+          - version
+        properties:
+          status:
+            type: string
+            enum:
+              - running
+          version:
+            type: string

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

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="./swagger-ui.css" />
+    <link rel="stylesheet" type="text/css" href="index.css" />
+    <link rel="icon" type="image/png" href="./favicon-32x32.png" sizes="32x32" />
+    <link rel="icon" type="image/png" href="./favicon-16x16.png" sizes="16x16" />
+  </head>
+
+  <body>
+    <div id="swagger-ui"></div>
+    <script src="./swagger-ui-bundle.js" charset="UTF-8"> </script>
+    <script src="./swagger-ui-standalone-preset.js" charset="UTF-8"> </script>
+    <script src="./swagger-initializer.js" charset="UTF-8"> </script>
+  </body>
+</html>

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>

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