From 9960baa9c8d4243122722d2420043de378f4f3c9 Mon Sep 17 00:00:00 2001
From: Piero Toffanin <pt@masseranolabs.com>
Date: Sat, 9 Oct 2021 10:04:16 -0400
Subject: [PATCH] Swagger docs definition

---
 app/app.py | 80 ++++++++++++++++++++++++++++++++++++++++++++++--------
 1 file changed, 68 insertions(+), 12 deletions(-)

diff --git a/app/app.py b/app/app.py
index 44e21c1..659409f 100644
--- a/app/app.py
+++ b/app/app.py
@@ -566,6 +566,9 @@ def create_app(args):
                 frontendTimeout:
                   type: integer
                   description: Frontend translation timeout
+                suggestions:
+                  type: boolean
+                  description: Whether submitting suggestions is enabled.
                 language:
                   type: object
                   properties:
@@ -606,21 +609,65 @@ def create_app(args):
             }
         )
 
-    swag = swagger(app)
-    swag["info"]["version"] = "1.2"
-    swag["info"]["title"] = "LibreTranslate"
-
-    @app.route("/spec")
-    @limiter.exempt
-    def spec():
-        return jsonify(swag)
-
-
     @app.route("/suggest", methods=["POST"])
     @limiter.exempt
     def suggest():
-        if args.suggestions is False:
-            abort(404)
+        """
+        Submit a suggestion to improve a translation
+        ---
+        tags:
+          - feedback
+        parameters:
+          - in: formData
+            name: q
+            schema:
+              type: string
+              example: Hello world!
+            required: true
+            description: Original text
+          - in: formData
+            name: s
+            schema:
+              type: string
+              example: ¡Hola mundo!
+            required: true
+            description: Suggested translation
+          - in: formData
+            name: source
+            schema:
+              type: string
+              example: en
+            required: true
+            description: Language of original text
+          - in: formData
+            name: target
+            schema:
+              type: string
+              example: es
+            required: true
+            description: Language of suggested translation
+        responses:
+          200:
+            description: Success
+            schema:
+              id: suggest-response
+              type: object
+              properties:
+                success:
+                  type: boolean
+                  description: Whether submission was successful
+          403:
+            description: Not authorized
+            schema:
+              id: error-response
+              type: object
+              properties:
+                error:
+                  type: string
+                  description: Error message
+        """
+        if not args.suggestions:
+            abort(403, description="Suggestions are disabled on this server.")
 
         q = request.values.get("q")
         s = request.values.get("s")
@@ -630,6 +677,15 @@ def create_app(args):
         SuggestionsDatabase().add(q, s, source_lang, target_lang)
         return jsonify({"success": True})
 
+    swag = swagger(app)
+    swag["info"]["version"] = "1.2.1"
+    swag["info"]["title"] = "LibreTranslate"
+
+    @app.route("/spec")
+    @limiter.exempt
+    def spec():
+        return jsonify(swag)
+
     SWAGGER_URL = "/docs"  # URL for exposing Swagger UI (without trailing '/')
     API_URL = "/spec"