ADD: basic swagger setup (#152)

frontend/generate_base_model.py

+import json
+
 import requests
 import os
 
 AUTH = os.getenv('NETDB_AUTH')
-API_BASE_URL = "https://www-net-devel.scc.kit.edu/api/3.0"
+API_SCHEME = 'https'
+API_HOST = 'www-net-devel.scc.kit.edu'
+API_VERSION = '3.0'
+API_BASE_URL = f'/api/{API_VERSION}'
 BASE_DIR = 'src/api-services.gen/'
 
+SWAGGER_TARGET_FILE = 'public/api.json'
+
+swagger = {'swagger': '2.0',
+           'info': {
+               'description': """
+Die Schnittstelle WebAPI bietet IT-Betreuern am KIT die Möglichkeit, eigene, speziell zugeschnittene Anwendungsprogramme für die Pflege ihrer netzwerk-spezifischen Anwendungsdaten (wie z.B. DNS) aufzubauen.
+Die Schnittstelle setzt auf der Netzdatenbank des SCC (NetDB) auf und ist für eine vollautomatisierte Nutzung auf Basis des heutzutage üblichen textbasierten Datenaustauschformates JSON (JavaScript Object Notation) vorgesehen (s.a. http://de.wikipedia.org/wiki/JavaScript_Object_Notation).
+Sie ist über HTTPS erreichbar und kann dadurch mit jeder beliebigen HTTP-Programmbibliothek benutzt werden. Im Rahmen der implementierten Systeme (Anwendungsbereiche), Objekttypen und Funktionen lassen sich sämtliche Daten durch entsprechende Dienstanforderungen (Requests) sowohl ausgeben bzw. abfragen als auch manipulieren (im Standardfall Eintragen, Ändern, Löschen). Die konkreten, jeweils versionsspezifischen Informationen und Parameter zu diesen Systemen, Objekttypen und Funktionen sind nicht Bestandteil dieser Dokumentation, sondern über selbstdokumentierende Indexabfragen der WebAPI erreichbar.""",
+               'version': API_VERSION,
+               'title': 'SCC NETDB-API'},
+
+           'externalDocs': {
+               'description': 'Weitere Dokumentation',
+               'url': f'https://www-net-devel-doku.scc.kit.edu/webapi/{API_VERSION}/'
+           },
+           'host': '',
+           'basePath': API_BASE_URL,
+           #'schemes': [API_SCHEME],
+           'tags': [],
+           'paths': []
+           }
+
 keyword_replacements = {'class': 'cls'}
 
 files = {}
-request = requests.get("{base}/wapi/function/list".format(base=API_BASE_URL), headers={'Authorization': AUTH})
+sess = requests.Session()
+sess.headers.update({'Authorization': AUTH})
+request = sess.get("{scheme}://{base_host}{base_url}/wapi/function/list".format(scheme=API_SCHEME, base_host=API_HOST,
+                                                                                base_url=API_BASE_URL))
 if not request.status_code == 200:
     print("Fail! Unexpected status_code", request.status_code)
     print("Is the NETDB_AUTH environment variable correct?")
@@ -38,7 +68,7 @@ export default {
         old_default = None
         new_default = None
         p_esc = p
-        for (unesc,esc) in keyword_replacements.items():
+        for (unesc, esc) in keyword_replacements.items():
             p_esc = p_esc.replace(unesc, esc)
         if 'old' in v:
             old_default = v['old']['dataDefault']
@@ -56,7 +86,7 @@ export default {
                 params_dict_old += '\'{p}\': {p_esc}_old, '.format(p=p, p_esc=p_esc)
             params_str += '{p_esc}_old={d}, '.format(p_esc=p_esc, p=p, d=old_default)
         if 'new' in v:
-            params_str += '{p}_new={d}, '.format(p=p,d=new_default)
+            params_str += '{p}_new={d}, '.format(p=p, d=new_default)
             params_dict_new += '\'{p}\': {p}_new, '.format(p=p)
 
     params_dict_new += '}'
@@ -94,10 +124,40 @@ export default {
         return Axios.get(`${{NETVSConfig.NETDB_API_BASE_URL}}/{fq_name_slash}`, cnf)
     }},
 """
-    f_handle.write(func_str.format(params_dict_old=params_dict_old, params_dict=params_dict, name=f['name'], params=params_str, fq_name_slash=f['fq_name'].replace('.', '/')))
+    f_handle.write(
+        func_str.format(params_dict_old=params_dict_old, params_dict=params_dict, name=f['name'], params=params_str,
+                        fq_name_slash=f['fq_name'].replace('.', '/')))
 
 for f in files.values():
     f.write("""}
 """)
     f.close()
 
+systems = sess.get(
+    "{scheme}://{base_host}{base_url}/".format(scheme=API_SCHEME, base_host=API_HOST, base_url=API_BASE_URL))
+swagger['tags'] = systems.json()[0]
+swagger['securityDefinitions'] = {'api_key': {'type': 'apiKey', 'name': 'Authorization', 'in': 'header'}}
+swagger['paths'] = {f"/{f['system']}/{f['object_type']}/{f['name']}": {
+    'post' if f['is_data_manipulating'] else 'get': {'parameters': [
+        {'name': p, 'description': d['description'],
+         'required': d['old']['isRequired'] if 'old' in d else d['new']['isRequired'], 'schema': {
+         'type': d['dataType']['jsonName']}, 'in': 'body' if f['is_data_manipulating'] else 'query'} for p, d in f['parameters'].items()],
+        'produces': ['application/json'] if f['is_returning'] else [], 'tags': [f['system']], 'security': [{'api_key':[]}],
+    'responses':{
+        200: {
+            'description': 'Request erfolgreich',
+        },
+        400: {
+            'description': 'Eingabefehler',
+        },
+        401: {
+            'description': 'Unauthorisiert',
+        },
+        500: {
+            'description': 'Interner Serverfehler.',
+        },
+    }}} for f
+    in
+    func_index}
+with open(SWAGGER_TARGET_FILE, 'w') as f:
+    f.write(json.dumps(swagger))

frontend/package.json

@@ -22,6 +22,7 @@
     "npm": "^6.13.0",
     "popper.js": "^1.14.7",
     "sass-loader": "^7.1.0",
+    "swagger-ui": "^3.24.3",
     "v-debounce": "^0.1.2",
     "vue": "^2.6.0",
     "vue-awesome": "^3.4.0",

frontend/public/.gitignore

+api.json
\ No newline at end of file

frontend/src/App.vue

@@ -62,7 +62,7 @@
                         <hr>
                         <p class="pull-right d-print-none">
                             <a target="_blank" href="https://www-net-doku.scc.kit.edu/webapi/release/dnscfg-perms/"><font-awesome-icon :icon="['far', 'life-ring']"></font-awesome-icon> Hilfe/Dokumentation</a> |
-                            <a target="_blank" href="https://www-net-devel-doku.scc.kit.edu/webapi/release/intro/"><font-awesome-icon icon="code"></font-awesome-icon> API</a> |
+                            <b-link to="/swagger"><font-awesome-icon icon="code"></font-awesome-icon> API</b-link> |
                             <a target="_blank" href="https://git.scc.kit.edu/scc-net/net-suite/net-suite/issues"><font-awesome-icon icon="bug"></font-awesome-icon> Fehler melden</a> |
                             Kontakt: <a href="mailto:dns-betrieb@scc.kit.edu">dns-betrieb∂scc.kit.edu</a>
                         </p>

frontend/src/router.js

@@ -10,6 +10,16 @@ export default new Router({
         {
             path: '/', beforeEnter: (to, from, next) => next('/dnsvs')
         },
+        {
+            path: '/swagger',
+            name: 'wagger-ui',
+            component: () => import('./views/swagger/ui.vue'),
+            meta: {
+                resolveName: function () {
+                    return "API-Browser"
+                }
+            }
+        },
         {
             path: '/login',
             name: 'login',

frontend/src/views/swagger/ui.vue

+<template>
+    <div id="swagger-ui">
+    </div>
+</template>
+
+<script>
+    import SwaggerUI from 'swagger-ui'
+    import 'swagger-ui/dist/swagger-ui.css'
+
+    export default {
+        name: "ui.vue",
+        mounted() {
+            SwaggerUI({
+                url: '/api.json',
+                dom_id: '#swagger-ui',
+                deepLinking: false,
+                presets: [
+                    SwaggerUI.presets.apis
+                ],
+                plugins: [
+                    SwaggerUI.plugins.DownloadUrl
+                ]
+            })
+        },
+        created() {
+        }
+    }
+</script>
+
+<style scoped>
+
+</style>