From 44092d7dd9b704059e1712a2581d3b8fe3ed5c3c Mon Sep 17 00:00:00 2001
From: bpetschowitsch <bernhard.petschowitsch@hochschule-burgenland.at>
Date: Wed, 13 May 2026 16:19:59 +0200
Subject: [PATCH] Create 12_swagger.md

---
 12_swagger.md | 87 +++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 87 insertions(+)
 create mode 100644 12_swagger.md

diff --git a/12_swagger.md b/12_swagger.md
new file mode 100644
index 0000000..55413f1
--- /dev/null
+++ b/12_swagger.md
@@ -0,0 +1,87 @@
+# Webservice - Documentation
+
+## Swagger
+include the metadata/description to the webapplication
+
+```bash
+vi /opt/webservice/webservice.py
+```
+
+```python
+from flask import Flask
+from flask_restx import Api, Resource, fields
+from werkzeug.middleware.proxy_fix import ProxyFix
+
+app = Flask(__name__)
+app.wsgi_app = ProxyFix(app.wsgi_app, x_prefix=1)
+
+api = Api(app, 
+    version='1.0', 
+    title='Addressbook API',
+    description='Mega Fancy Addressbok'
+)
+
+name_model = api.model('NameInput', {
+    'name': fields.String(required=True, description='Neuer Name')
+})
+
+names_list = ["Alice", "Bob", "Charlie"]
+
+@api.route('/names')
+class AddressList(Resource):
+    
+    @api.doc('get_names')
+    def get(self):
+        """Gibt die gesamte Liste zurück"""
+        return names_list
+
+    @api.expect(name_model) # Validierung & Dokumentation für den POST-Body
+    @api.doc('add_name')
+    @api.response(201, 'Erfolgreich hinzugefügt')
+    @api.response(400, 'Ungültige Daten')
+    def post(self):
+        """Fügt einen neuen Namen hinzu"""
+        data = api.payload
+        if "name" in data:
+            names_list.append(data["name"])
+            return {"status": "success"}, 201
+        api.abort(400, "Ungültige Daten")
+
+    @api.doc('delete_all_names')
+    def delete(self):
+        """Leert die gesamte Liste"""
+        names_list.clear()
+        return {"status": "Liste geleert"}, 200
+
+if __name__ == '__main__':
+    app.run(host='127.0.0.1', port=5000, debug=True)
+```
+
+## Reverse-Proxy
+
+Make the webservice documentation available through nginx.
+
+```bash
+sudo vi /etc/nginx/sites-available/*site-name*
+```
+
+add to the server section:
+
+```nginx
+# API Queries are forwarded to Flask
+location /api/doc {
+    proxy_pass http://127.0.0.1:5000/;
+    proxy_set_header X-Forwarded-Prefix /api/doc;
+}
+```
+
+reload nginx, start the webservice:
+
+```bash
+sudo systemctl reload nginx
+/opt/webservice/venv/bin/gunicorn -w 1 -b 127.0.0.1:5000 webservice:app
+```
+
+Verify the webservice Documentation via your browser.
+
+URL: `https://*domain-name*/api/doc`