tornado_swagger_ui support query operation in "GET" method, and support methods in...

[releng.git] / utils / test / result_collection_api / tornado_swagger_ui / README.md

diff --git a/utils/test/result_collection_api/tornado_swagger_ui/README.md b/utils/test/result_collection_api/tornado_swagger_ui/README.md
index 1ae3834..e90e130 100644 (file)
--- a/utils/test/result_collection_api/tornado_swagger_ui/README.md
+++ b/utils/test/result_collection_api/tornado_swagger_ui/README.md
@@ -28,9 +28,9 @@ class ItemNoParamHandler(GenericApiHandler):
     @swagger.operation(nickname='create')
     def post(self):
         """
-            @param body: create test results for a pod.
+            @param body: create test results for a item.
             @type body: L{Item}
-            @return 200: pod is created.
+            @return 200: item is created.
             @raise 400: invalid input
         """
 
@@ -49,9 +49,9 @@ class ItemNoParamHandler(GenericApiHandler):
 
 def make_app():
     return swagger.Application([
-        (r"/pods", ItemNoParamHandler),
-        (r"/pods/([^/]+)", ItemHandler),
-        (r"/projects/([^/]+)/cases/([^/]+)", ItemOptionParamHandler),
+        (r"/items", ItemNoParamHandler),
+        (r"/items/([^/]+)", ItemHandler),
+        (r"/items/([^/]+)/cases/([^/]+)", ItemOptionParamHandler),
     ])
 
 # You define models like this:
@@ -157,6 +157,101 @@ class Item:
             ]
         }
     }
+
+# if you want to declare an list property, you can do it like this:
+class Item:
+    """
+        @ptype property3: L{PropertySubclass}
+        @ptype property4: C{list} of L{PropertySubclass}
+    """
+    def __init__(self, property1, property2, property3, property4=None):
+        self.property1 = property1
+        self.property2 = property2
+        self.property3 = property3
+        self.property4 = property4
+
+# Swagger json:
+    "models": {
+        "Item": {
+            "description": "A description...",
+            "id": "Item",
+            "required": [
+                "property1",
+            ],
+            "properties": [
+                "property1": {
+                    "type": "string"
+                },
+                "property2": {
+                    "type": "string"
+                },
+                "property3": {
+                    "type": "PropertySubclass"
+                    "default": null
+                },
+                "property4": {
+                    "default": null,
+                    "items": {
+                        "type": "PropertySubclass"},
+                        "type": "array"
+                    }
+                }
+            ]
+        }
+    }
+
+# if it is a query:
+class ItemQueryHandler(GenericApiHandler):
+    @swagger.operation(nickname='query')
+    def get(self):
+        """
+           @param property1:
+           @type property1: L{string}
+           @in property1: query
+           @required property1: False
+
+           @param property2:
+           @type property2: L{string}
+           @in property2: query
+           @required property2: True
+           @rtype: L{Item}
+
+           @notes: GET /item?property1=1&property2=1
+        """
+
+# Swagger json:
+    "apis": [
+        {
+            "operations": [
+                {
+                    "parameters": [
+                        {
+                            "name": "property1",
+                            "dataType": "string",
+                            "paramType": "query",
+                            "description": ""
+                        },
+                        {
+                            "name": "property2",
+                            "dataType": "string",
+                            "paramType": "query",
+                            "required": true,
+                            "description": ""
+                        }
+                    ],
+                    "responseClass": "Item",
+                    "notes": null,
+                    "responseMessages": [],
+                    "summary": null,
+                    "httpMethod": "GET",
+                    "nickname": "query"
+                }
+            ],
+            "path": "/item",
+            "description": null
+        },
+        ....
+    ]
 ```
 
 # Running and testing