Add swagger api documentation

526f1215 · Marc Feger · ccdab5f1 · 526f1215 · 526f1215 · 526f1215
Commit 526f1215 authored Mar 8, 2019 by Marc Feger
--- a/api/browser_guide/templates/inline_quoted.html.erb
+++ b/api/browser_guide/templates/inline_quoted.html.erb
--- a/api/browser_guide/templates/section.html.erb
+++ b/api/browser_guide/templates/section.html.erb
--- a/api/doc/swagger-ui/index.html
+++ b/api/doc/swagger-ui/index.html
+<!-- HTML for static distribution bundle build -->
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8">
+    <title>NeoDB API</title>
+    <link rel="stylesheet" type="text/css" href="../../static/swagger/swagger-ui.css" >
+    <link rel="icon" type="image/png" href="../../static/swagger/favicon-32x32.png" sizes="32x32" />
+    <link rel="icon" type="image/png" href="../../static/swagger/favicon-16x16.png" sizes="16x16" />
+    <style>
+      html
+      {
+        box-sizing: border-box;
+        overflow: -moz-scrollbars-vertical;
+        overflow-y: scroll;
+      }
+
+      *,
+      *:before,
+      *:after
+      {
+        box-sizing: inherit;
+      }
+
+      body
+      {
+        margin:0;
+        background: #fafafa;
+      }
+    </style>
+  </head>
+
+  <body>
+    <div id="swagger-ui"></div>
+
+    <script src="../../static/swagger/swagger-ui-bundle.js"> </script>
+    <script src="../../static/swagger/swagger-ui-standalone-preset.js"> </script>
+    <script>
+    window.onload = function() {
+      // Begin Swagger UI call region
+      const ui = SwaggerUIBundle({
+        url: "../static/swagger/neo_api.yaml",
+        dom_id: '#swagger-ui',
+        deepLinking: true,
+        presets: [
+          SwaggerUIBundle.presets.apis,
+          SwaggerUIStandalonePreset
+        ],
+        plugins: [
+          SwaggerUIBundle.plugins.DownloadUrl
+        ],
+        layout: "StandaloneLayout"
+      })
+      // End Swagger UI call region
+
+      window.ui = ui
+    }
+  </script>
+  </body>
+</html>
--- a/api/doc/swagger-ui/oauth2-redirect.html
+++ b/api/doc/swagger-ui/oauth2-redirect.html
+<!doctype html>
+<html lang="en-US">
+<body onload="run()">
+</body>
+</html>
+<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);
+        } 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.code) {
+            if (!isValid) {
+                oauth2.errCb({
+                    authId: oauth2.auth.name,
+                    source: "auth",
+                    level: "warning",
+                    message: "Authorization may be unsafe, passed state was changed in server 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();
+    }
+</script>
--- a/api/server.py
+++ b/api/server.py
-from flask import Flask, render_template, jsonify, request, Response
+from flask import Flask, render_template, jsonify, request
 from flask_cors import CORS

-from api.browser_guide.examplegraph import ExampleGraph
+from api.doc.browser_guide.examplegraph import ExampleGraph
 from api.src.models.discussion_skeleton import DiscussionSkeleton
 from api.src.models.discussion import Discussion

@@ -13,6 +13,11 @@ CORS(app)
 def load(q):
    if q == 'example_graph':
        return jsonify(ExampleGraph().inject_to_neo())
+    elif q == 'guide':
+        guide = request.args.get('guide')
+        if not guide:
+            return jsonify({"error": "Parameter guide is missing"}), 404
+        return render_template('doc/browser_guide/html/' + guide)
    elif q == 'dbas_live':
        slug = request.args.get('slug')
        if not slug:
@@ -25,11 +30,11 @@ def load(q):
        return jsonify(DiscussionSkeleton(protocol='http',
                                          host='web',
                                          port='4284').inject_to_neo())
-    elif q == 'guide':
-        guide = request.args.get('guide')
-        if not guide:
-            return jsonify({"error": "Parameter guide is missing"}), 404
-        return render_template('browser_guide/html/' + guide)
+
+
+@app.route('/')
+def swagger():
+    return render_template('doc/swagger-ui/' + 'index.html')


 if __name__ == '__main__':

--- a/api/src/models/discussion.py
+++ b/api/src/models/discussion.py
--- a/api/src/models/discussion_skeleton.py
+++ b/api/src/models/discussion_skeleton.py
--- a/api/static/swagger/favicon-16x16.png
+++ b/api/static/swagger/favicon-16x16.png
--- a/api/static/swagger/favicon-32x32.png
+++ b/api/static/swagger/favicon-32x32.png
--- a/api/static/swagger/neo_api.yaml
+++ b/api/static/swagger/neo_api.yaml
+openapi: 3.0.0
+servers:
+  - url: 'http://localhost:5000'
+info:
+  version: "1.0"
+  title: NeoDB
+
+paths:
+  /load/example_graph:
+    get:
+      summary: Load the Graph which is used in the browser-guide for collaborative-filterung Recommender
+      description: >-
+        This function loads the graph for the browser guide using collaborative recommender algorithms.
+        The graph is composed of the nodes Issue, Statement and Users.
+        Several Cypher queries are executed internally. The result shows how long the individual steps took.
+      tags:
+        - Browser Guide
+      responses:
+        200:
+          description: OK
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  delete_time:
+                    type: number
+                  delete_zero_ratings_time:
+                    type: number
+                  index_time:
+                    type: number
+                  issue_node_time:
+                    type: number
+                  random_ratings_time:
+                    type: number
+                  statement_content_time:
+                    type: number
+                  statement_node_time:
+                    type: number
+                  statement_to_issue_time:
+                    type: number
+                  statement_user_relation_time:
+                    type: number
+                  total:
+                    type: number
+                  user_node_time:
+                    type: number
+                  user_rates_own_positions_time:
+                    type: number
+
+  /load/guide:
+    get:
+      summary: Load the Graph which is used in the browser-guide for collaborative-filterung Recommender
+      description: >-
+        This function loads the graph for the browser guide using collaborative recommender algorithms.
+        The graph is composed of the nodes Issue, Statement and Users.
+        Several Cypher queries are executed internally. The result shows how long the individual steps took.
+      tags:
+        - Browser Guide
+
+      parameters:
+        - in: query
+          name: guide
+          schema:
+            type: string
+          description: The name of the HTML file which includes the browser guide.
+
+      responses:
+        200:
+          description: File exist
+        404:
+          description: guide is missing
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  error:
+                    type: string
+        # Todo: Not listed if wrong call
+        500:
+          description: File does not exist
+
+  /load/dbas_live:
+    get:
+      summary: Load a dicussion by its slug from the D-BAS live version
+      description: >-
+        This route invites a discussion with a particular slug.
+        The internal D-BAS interface GraphQL is used.
+        GraphQl provides the corresponding Cypher query on the D-BAS side.
+      tags:
+        - D-BAS live
+
+      parameters:
+        - in: query
+          name: slug
+          schema:
+            type: string
+          description: The slug of the discusion which should be queried from the live version.
+
+      responses:
+        200:
+          description: OK
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  total_time:
+                    type: number
+        404:
+          description: slug is missing
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  error:
+                    type: string
+
+  /load/skeleton:
+    get:
+      summary: This route loads every discussion graph
+      description: >-
+        This route loads any discusion graph from the D-BAS database.
+        Only the basic skeleton consisting of arguments and statements is loaded.
+      tags:
+        - Discussion-Graphs
+
+      responses:
+        200:
+          description: OK
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  total_time:
+                    type: number
+
--- a/api/static/swagger/swagger-ui-bundle.js
+++ b/api/static/swagger/swagger-ui-bundle.js
--- a/api/static/swagger/swagger-ui-bundle.js.map
+++ b/api/static/swagger/swagger-ui-bundle.js.map
--- a/api/static/swagger/swagger-ui-standalone-preset.js
+++ b/api/static/swagger/swagger-ui-standalone-preset.js
--- a/api/static/swagger/swagger-ui-standalone-preset.js.map
+++ b/api/static/swagger/swagger-ui-standalone-preset.js.map
--- a/api/static/swagger/swagger-ui.css
+++ b/api/static/swagger/swagger-ui.css
--- a/api/static/swagger/swagger-ui.css.map
+++ b/api/static/swagger/swagger-ui.css.map
+{"version":3,"sources":[],"names":[],"mappings":"","file":"swagger-ui.css","sourceRoot":""}
\ No newline at end of file
--- a/api/static/swagger/swagger-ui.js
+++ b/api/static/swagger/swagger-ui.js
--- a/api/static/swagger/swagger-ui.js.map
+++ b/api/static/swagger/swagger-ui.js.map