update minimal example in readme

mahenzon · mahenzon · commit e767a8e1f877 · 2021-05-27T12:48:22.000+03:00
diff --git a/README.rst b/README.rst
@@ -62,6 +62,18 @@ A minimal API
         id = fields.Integer(as_string=True, dump_only=True)
         name = fields.String()
 
+    @pre_load
+    def remove_id_before_deserializing(self, data, **kwargs):
+        """
+        We don't want to allow editing ID on POST / PATCH
+
+        Related issues:
+        https://github.com/AdCombo/flask-combo-jsonapi/issues/34
+        https://github.com/miLibris/flask-rest-jsonapi/issues/193
+        """
+        if 'id' in data:
+            del data['id']
+        return data
 
     # Create resource managers
     class PersonList(ResourceList):
diff --git a/docs/http_snippets/README.md b/docs/http_snippets/README.md
@@ -60,3 +60,5 @@ python3 update_snippets_with_responses.py
 
 > **Pro tip:** run webserver for specs before running update_snippets_with_responses, otherwise it won't work 😉 
 
+
+Copy-paste resulting help text (from between the "===" lines) to make includes.
diff --git a/docs/http_snippets/minimal_api__delete_person.json b/docs/http_snippets/minimal_api__delete_person.json
@@ -0,0 +1,13 @@
+{
+  "method": "DELETE",
+  "url": "http://localhost:5000/persons/1",
+  "httpVersion": "HTTP/1.1",
+  "queryString": [
+  ],
+  "headers": [
+    {
+      "name": "content-type",
+      "value": "application/vnd.api+json"
+    }
+  ]
+}
diff --git a/docs/http_snippets/minimal_api__get_person.json b/docs/http_snippets/minimal_api__get_person.json
@@ -1,6 +1,6 @@
 {
   "method": "GET",
-  "url": "http://localhost:5000/persons",
+  "url": "http://localhost:5000/persons/1",
   "httpVersion": "HTTP/1.1",
   "queryString": [
   ],
diff --git a/docs/http_snippets/minimal_api__get_persons.json b/docs/http_snippets/minimal_api__get_persons.json
@@ -0,0 +1,13 @@
+{
+  "method": "GET",
+  "url": "http://localhost:5000/persons",
+  "httpVersion": "HTTP/1.1",
+  "queryString": [
+  ],
+  "headers": [
+    {
+      "name": "content-type",
+      "value": "application/vnd.api+json"
+    }
+  ]
+}
diff --git a/docs/http_snippets/minimal_api__patch_person.json b/docs/http_snippets/minimal_api__patch_person.json
@@ -0,0 +1,17 @@
+{
+  "method": "PATCH",
+  "url": "http://localhost:5000/persons/1",
+  "httpVersion": "HTTP/1.1",
+  "queryString": [
+  ],
+  "headers": [
+    {
+      "name": "content-type",
+      "value": "application/vnd.api+json"
+    }
+  ],
+  "postData": {
+    "mimeType": "application/json",
+    "text": "{\n  \"data\": {\n    \"id\": 1,\n    \"type\": \"person\",\n    \"attributes\": {\n        \"name\": \"Sam\"\n    }\n  }\n}"
+  }
+}
diff --git a/docs/http_snippets/snippets/minimal_api__delete_person b/docs/http_snippets/snippets/minimal_api__delete_person
@@ -0,0 +1,5 @@
+DELETE /persons/1 HTTP/1.1
+Content-Type: application/vnd.api+json
+Host: localhost:5000
+
+
diff --git a/docs/http_snippets/snippets/minimal_api__delete_person_result b/docs/http_snippets/snippets/minimal_api__delete_person_result
@@ -0,0 +1,11 @@
+HTTP/1.1 200 OK
+Content-Type: application/vnd.api+json
+
+{
+  "jsonapi": {
+    "version": "1.0"
+  },
+  "meta": {
+    "message": "Object successfully deleted"
+  }
+}
diff --git a/docs/http_snippets/snippets/minimal_api__get_person b/docs/http_snippets/snippets/minimal_api__get_person
@@ -1,3 +1,5 @@
-GET /persons HTTP/1.1
+GET /persons/1 HTTP/1.1
 Content-Type: application/vnd.api+json
 Host: localhost:5000
+
+
diff --git a/docs/http_snippets/snippets/minimal_api__get_person_result b/docs/http_snippets/snippets/minimal_api__get_person_result
@@ -2,38 +2,20 @@ HTTP/1.1 200 OK
 Content-Type: application/vnd.api+json
 
 {
-  "data": [
-    {
-      "attributes": {
-        "name": "John"
-      },
-      "id": "1",
-      "links": {
-        "self": "/persons/1"
-      },
-      "type": "person"
+  "data": {
+    "attributes": {
+      "name": "John"
     },
-    {
-      "attributes": {
-        "name": "Sam"
-      },
-      "id": "2",
-      "links": {
-        "self": "/persons/2"
-      },
-      "type": "person"
-    }
-  ],
+    "id": "1",
+    "links": {
+      "self": "/persons/1"
+    },
+    "type": "person"
+  },
   "jsonapi": {
     "version": "1.0"
   },
   "links": {
-    "first": "http://localhost:5000/persons",
-    "last": "http://localhost:5000/persons?page%5Bnumber%5D=2",
-    "next": "http://localhost:5000/persons?page%5Bnumber%5D=2",
-    "self": "http://localhost:5000/persons"
-  },
-  "meta": {
-    "count": 2
+    "self": "/persons/1"
   }
 }
diff --git a/docs/http_snippets/snippets/minimal_api__get_persons b/docs/http_snippets/snippets/minimal_api__get_persons
@@ -0,0 +1,5 @@
+GET /persons HTTP/1.1
+Content-Type: application/vnd.api+json
+Host: localhost:5000
+
+
diff --git a/docs/http_snippets/snippets/minimal_api__get_persons_result b/docs/http_snippets/snippets/minimal_api__get_persons_result
@@ -0,0 +1,26 @@
+HTTP/1.1 200 OK
+Content-Type: application/vnd.api+json
+
+{
+  "data": [
+    {
+      "attributes": {
+        "name": "John"
+      },
+      "id": "1",
+      "links": {
+        "self": "/persons/1"
+      },
+      "type": "person"
+    }
+  ],
+  "jsonapi": {
+    "version": "1.0"
+  },
+  "links": {
+    "self": "http://localhost:5000/persons"
+  },
+  "meta": {
+    "count": 1
+  }
+}
diff --git a/docs/http_snippets/snippets/minimal_api__patch_person b/docs/http_snippets/snippets/minimal_api__patch_person
@@ -0,0 +1,14 @@
+PATCH /persons/1 HTTP/1.1
+Content-Type: application/vnd.api+json
+Host: localhost:5000
+Content-Length: 102
+
+{
+  "data": {
+    "id": 1,
+    "type": "person",
+    "attributes": {
+        "name": "Sam"
+    }
+  }
+}
diff --git a/docs/http_snippets/snippets/minimal_api__patch_person_result b/docs/http_snippets/snippets/minimal_api__patch_person_result
@@ -0,0 +1,21 @@
+HTTP/1.1 200 OK
+Content-Type: application/vnd.api+json
+
+{
+  "data": {
+    "attributes": {
+      "name": "Sam"
+    },
+    "id": "1",
+    "links": {
+      "self": "/persons/1"
+    },
+    "type": "person"
+  },
+  "jsonapi": {
+    "version": "1.0"
+  },
+  "links": {
+    "self": "/persons/1"
+  }
+}
diff --git a/docs/http_snippets/update_snippets_with_responses.py b/docs/http_snippets/update_snippets_with_responses.py
@@ -16,6 +16,38 @@
 REMOVE_PYTHON_SNIPPET = True
 
 
+SORTING_ORDER = [
+    "create",
+    "get",
+    "patch",
+    "delete",
+]
+
+ORDER_POS = {
+    i: v for i, v in enumerate(SORTING_ORDER)
+}
+
+
+class StrOrderCRUD:
+    def __init__(self, inner):
+        self.inner = inner
+
+    def __lt__(self, other):
+        index_1 = -1
+        index_2 = -1
+        for index, name in ORDER_POS.items():
+            substring = f"__{name}_"
+            if substring in self.inner:
+                index_1 = index
+            if substring in other.inner:
+                index_2 = index
+
+        if index_1 != index_2:
+            return index_1 < index_2
+
+        return self.inner < other.inner
+
+
 def run_request_for_module(module_name: str):
     log.info("Start processing %r", module_name)
 
@@ -71,18 +103,69 @@ def run_request_for_module(module_name: str):
     log.info("Processed %r", module_name)
 
 
+def add_help_lines(lines: list, module_name: str) -> None:
+    """
+
+    Append help lines to create smth like this:
+
+    '''
+
+    Request:
+
+    .. literalinclude:: ./http_snippets/snippets/minimal_api__create_person
+      :language: HTTP
+
+    Response:
+
+    .. literalinclude:: ./http_snippets/snippets/minimal_api__create_person_result
+      :language: HTTP
+
+    '''
+
+    """
+    literalinclude_file =  ".. literalinclude:: ./http_snippets/snippets/" + module_name
+    rst_language_http    = "  :language: HTTP"
+
+    lines.append("")
+    lines.append("Request:")
+    lines.append("")
+    lines.append(literalinclude_file)
+    lines.append(rst_language_http)
+    lines.append("")
+    lines.append("Response:")
+    lines.append("")
+    lines.append(literalinclude_file + SNIPPET_RESULT_POSTFIX)
+    lines.append(rst_language_http)
+    lines.append("")
+
+
 def main():
     log.warning("Starting")
 
-    for module_name in os.listdir(SNIPPETS_DIR):
-        if module_name.endswith(".py"):
+    modules_to_process = os.listdir(SNIPPETS_DIR)
+    log.debug("all available snippets: %s", modules_to_process)
+    modules_to_process.sort(key=StrOrderCRUD)
+    log.warning("modules to process (with order): %s", modules_to_process)
+
+    result_help_text = []
+    result_help_text.append("=" * 30)
+
+    for module_file in modules_to_process:
+        if module_file.endswith(".py"):
+            module_name = module_file[:-3]
             try:
-                run_request_for_module(module_name[:-3])
+                run_request_for_module(module_name)
             except Exception:
-                log.exception("Could not process module %r, skipping", module_name)
+                log.exception("Could not process module %r, skipping", module_file)
             else:
                 if REMOVE_PYTHON_SNIPPET:
-                    os.unlink("/".join((SNIPPETS_DIR, module_name)))
+                    os.unlink("/".join((SNIPPETS_DIR, module_file)))
+                add_help_lines(result_help_text, module_name)
+
+    result_help_text.append("=" * 30)
+    result_help_text.append("")
+
+    print("\n".join(result_help_text))
 
     log.warning("Done")
 
diff --git a/docs/minimal_api_example.rst b/docs/minimal_api_example.rst
@@ -9,3 +9,48 @@ Response:
 
 .. literalinclude:: ./http_snippets/snippets/minimal_api__create_person_result
   :language: HTTP
+
+
+Request:
+
+.. literalinclude:: ./http_snippets/snippets/minimal_api__get_person
+  :language: HTTP
+
+Response:
+
+.. literalinclude:: ./http_snippets/snippets/minimal_api__get_person_result
+  :language: HTTP
+
+
+Request:
+
+.. literalinclude:: ./http_snippets/snippets/minimal_api__get_persons
+  :language: HTTP
+
+Response:
+
+.. literalinclude:: ./http_snippets/snippets/minimal_api__get_persons_result
+  :language: HTTP
+
+
+Request:
+
+.. literalinclude:: ./http_snippets/snippets/minimal_api__patch_person
+  :language: HTTP
+
+Response:
+
+.. literalinclude:: ./http_snippets/snippets/minimal_api__patch_person_result
+  :language: HTTP
+
+
+Request:
+
+.. literalinclude:: ./http_snippets/snippets/minimal_api__delete_person
+  :language: HTTP
+
+Response:
+
+.. literalinclude:: ./http_snippets/snippets/minimal_api__delete_person_result
+  :language: HTTP
+
diff --git a/examples/api_minimal.py b/examples/api_minimal.py

Original file line number	Diff line number	Diff line change
`@@ -60,3 +60,5 @@ python3 update_snippets_with_responses.py`
`60`	`60`
`61`	`61`	`> Pro tip: run webserver for specs before running update_snippets_with_responses, otherwise it won't work 😉`
`62`	`62`
	`63`	`+`
	`64`	`+Copy-paste resulting help text (from between the "===" lines) to make includes.`
Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`	`1`	`{`
`2`	`2`	`"method": "GET",`
`3`		`- "url": "http://localhost:5000/persons",`
	`3`	`+ "url": "http://localhost:5000/persons/1",`
`4`	`4`	`"httpVersion": "HTTP/1.1",`
`5`	`5`	`"queryString": [`
`6`	`6`	`],`