CHECK-2284 update documentation to more explicitly call out that swag…

…ger docs wont work out of box (#257) * CHECK-2284 update documentation to more explicitly call out that swagger docs wont work out of box * MEEDAN-2284 fix whitespace
meedan · Sep 20, 2022 · 030fc10 · 030fc10
1 parent 2b9f6ff
commit 030fc10
Show file tree

Hide file tree

Showing 4 changed files with 9 additions and 9 deletions.
diff --git a/app/main/controller/audio_similarity_controller.py b/app/main/controller/audio_similarity_controller.py
@@ -18,14 +18,14 @@ class AudioSimilarityResource(Resource):
     def delete(self):
         return similarity.delete_item(request.args or request.json, "audio")
 
-    @api.response(200, 'text successfully stored in the similarity database.')
-    @api.doc('Store a text in the similarity database')
+    @api.response(200, 'audio successfully stored in the similarity database.')
+    @api.doc('Store an audio in the similarity database')
     @api.expect(audio_similarity_request, validate=True)
     def post(self):
         return similarity.add_item(request.args or request.json, "audio")
 
     @api.response(200, 'text similarity successfully queried.')
-    @api.doc('Make a text similarity query')
+    @api.doc('Make an audio similarity query. Note that we currently require GET requests with a JSON body rather than embedded params in the URL. You can achieve this via curl -X GET -H "Content-type: application/json" -H "Accept: application/json" -d \'{"url":"http://some.link/video.mp3", "threshold": 0.5}\' "http://[ALEGRE_HOST]/audio/similarity"')
     @api.doc(params={'url': 'audio URL to be stored or queried for similarity', 'threshold': 'minimum score to consider, between 0.0 and 1.0 (defaults to 0.9)', 'context': 'context'} )
     def get(self):
         return similarity.get_similar_items(request.args or request.json, "audio")
diff --git a/app/main/controller/image_similarity_controller.py b/app/main/controller/image_similarity_controller.py
@@ -39,7 +39,7 @@ def request_package(self, request):
     }
 
   @api.response(200, 'image similarity successfully queried.')
-  @api.doc('Make an image similarity query')
+  @api.doc('Make a image similarity query. Note that we currently require GET requests with a JSON body rather than embedded params in the URL. You can achieve this via curl -X GET -H "Content-type: application/json" -H "Accept: application/json" -d \'{"url":"http://some.link/video.mp4", "threshold": 0.5}\' "http://[ALEGRE_HOST]/image/similarity"')
   @api.doc(params={'url': 'image URL to be stored or queried for similarity', 'threshold': 'minimum score to consider, between 0.0 and 1.0 (defaults to 0.9)', 'context': 'context'})
   def get(self):
     return similarity.get_similar_items(self.request_package(request), "image")
diff --git a/app/main/controller/similarity_controller.py b/app/main/controller/similarity_controller.py
@@ -41,7 +41,7 @@ def post(self):
         return similarity.add_item(item, "text")
 
     @api.response(200, 'text similarity successfully queried.')
-    @api.doc('Make a text similarity query')
+    @api.doc('Make a text similarity query. Note that we currently require GET requests with a JSON body rather than embedded params in the URL. You can achieve this via curl -X GET -H "Content-type: application/json" -H "Accept: application/json" -d \'{"text":"Some Text", "threshold": 0.5, "model": "elasticsearch"}\' "http://[ALEGRE_HOST]/text/similarity"')
     @api.doc(params={'text': 'text to be stored or queried for similarity', 'threshold': 'minimum score to consider, between 0.0 and 1.0 (defaults to 0.9)', 'model': 'similarity model to use: "elasticsearch" (pure Elasticsearch, default) or the key name of an active model'})
     def get(self):
       return similarity.get_similar_items(similarity.get_body_for_text_document(request.args or request.json), "text")
diff --git a/app/main/controller/video_similarity_controller.py b/app/main/controller/video_similarity_controller.py
@@ -18,14 +18,14 @@ class VideoSimilarityResource(Resource):
     def delete(self):
         return similarity.delete_item(request.args or request.json, "video")
 
-    @api.response(200, 'text successfully stored in the similarity database.')
-    @api.doc('Store a text in the similarity database')
+    @api.response(200, 'video successfully stored in the similarity database.')
+    @api.doc('Store a video in the similarity database')
     @api.expect(video_similarity_request, validate=True)
     def post(self):
         return similarity.add_item(request.args or request.json, "video")
 
-    @api.response(200, 'text similarity successfully queried.')
-    @api.doc('Make a text similarity query')
+    @api.response(200, 'video similarity successfully queried.')
+    @api.doc('Make a video similarity query. Note that we currently require GET requests with a JSON body rather than embedded params in the URL. You can achieve this via curl -X GET -H "Content-type: application/json" -H "Accept: application/json" -d \'{"url":"http://some.link/video.mp4", "threshold": 0.5}\' "http://[ALEGRE_HOST]/video/similarity"')
     @api.doc(params={'url': 'video URL to be stored or queried for similarity', 'threshold': 'minimum score to consider, between 0.0 and 1.0 (defaults to 0.9)', 'context': 'context'} )
     def get(self):
         return similarity.get_similar_items(request.args or request.json, "video")