:sparkles: Upgrade docstring Markdown parsing (#163)

* :sparkles: Upgrade docstring Markdown parsing

* :memo: Update release notes

diff --git a/docs/img/tutorial/path-operation-configuration/image02.png b/docs/img/tutorial/path-operation-configuration/image02.png
index 6315a2e0fb4ae3d28ae8f39ab7f1892a07b247f3..f4aee92cad691c6319f551fec62582c7aec61c03 100644 (file)
Binary files a/docs/img/tutorial/path-operation-configuration/image02.png and b/docs/img/tutorial/path-operation-configuration/image02.png differ

diff --git a/docs/release-notes.md b/docs/release-notes.md
index 4165745def594d40b5f60ea29f59fb3ee3acecf2..4a8758c5938f1e293b05cf756797678f0b2bda2d 100644 (file)
--- a/docs/release-notes.md
+++ b/docs/release-notes.md
@@ -1,5 +1,7 @@
 ## Next release
 
+* Upgrade *path operation* `doctsring` parsing to support proper Markdown descriptions. New documentation at <a href="https://fastapi.tiangolo.com/tutorial/path-operation-configuration/#description-from-docstring" target="_blank">Path Operation Configuration</a>. PR <a href="https://github.com/tiangolo/fastapi/pull/163" target="_blank">#163</a>.
+
 * Upgrade Pydantic to version `0.23`. PR <a href="https://github.com/tiangolo/fastapi/pull/160" target="_blank">#160</a> by <a href="https://github.com/euri10" target="_blank">@euri10</a>.
 
 * Fix typo in Tutorial about Extra Models. PR <a href="https://github.com/tiangolo/fastapi/pull/159" target="_blank">#159</a> by <a href="https://github.com/danielmichaels" target="_blank">@danielmichaels</a>.

diff --git a/docs/src/path_operation_configuration/tutorial004.py b/docs/src/path_operation_configuration/tutorial004.py
index a4151a8cd0422c322d472fd11c5b5b85945427aa..f47d422e0c27effcb0ba6b73ec92dfb8bc3394d6 100644 (file)
--- a/docs/src/path_operation_configuration/tutorial004.py
+++ b/docs/src/path_operation_configuration/tutorial004.py
@@ -18,11 +18,11 @@ class Item(BaseModel):
 async def create_item(*, item: Item):
     """
     Create an item with all the information:
-    
-    * name: each item must have a name
-    * description: a long description
-    * price: required
-    * tax: if the item doesn't have tax, you can omit this
-    * tags: a set of unique tag strings for this item
+
+    - **name**: each item must have a name
+    - **description**: a long description
+    - **price**: required
+    - **tax**: if the item doesn't have tax, you can omit this
+    - **tags**: a set of unique tag strings for this item
     """
     return item

diff --git a/docs/src/path_operation_configuration/tutorial005.py b/docs/src/path_operation_configuration/tutorial005.py
index f710e6c669d322132e2dcb4843a6941ea5ad37e6..72d02ece396353a03683364298c8961d1c6860e4 100644 (file)
--- a/docs/src/path_operation_configuration/tutorial005.py
+++ b/docs/src/path_operation_configuration/tutorial005.py
@@ -23,11 +23,11 @@ class Item(BaseModel):
 async def create_item(*, item: Item):
     """
     Create an item with all the information:
-    
-    * name: each item must have a name
-    * description: a long description
-    * price: required
-    * tax: if the item doesn't have tax, you can omit this
-    * tags: a set of unique tag strings for this item
+
+    - **name**: each item must have a name
+    - **description**: a long description
+    - **price**: required
+    - **tax**: if the item doesn't have tax, you can omit this
+    - **tags**: a set of unique tag strings for this item
     """
     return item

diff --git a/docs/tutorial/path-operation-configuration.md b/docs/tutorial/path-operation-configuration.md
index ecbde573430db6e892432253c6fd9ae4b5a10a4b..0808adec9c4b3388f0e2625953c58e6edc0795af 100644 (file)
--- a/docs/tutorial/path-operation-configuration.md
+++ b/docs/tutorial/path-operation-configuration.md
@@ -42,6 +42,8 @@ You can add a `summary` and `description`:
 
 As descriptions tend to be long and cover multiple lines, you can declare the path operation description in the function <abbr title="a multi-line string as the first expression inside a function (not assigned to any variable) used for documentation">docstring</abbr> and **FastAPI** will read it from there.
 
+You can write <a href="https://en.wikipedia.org/wiki/Markdown" target="_blank">Markdown</a> in the docstring, it will be interpreted and displayed correctly (taking into account docstring indentation).
+
 ```Python hl_lines="19 20 21 22 23 24 25 26 27"
 {!./src/path_operation_configuration/tutorial004.py!}
 ```
@@ -50,9 +52,6 @@ It will be used in the interactive docs:
 
 <img src="/img/tutorial/path-operation-configuration/image02.png">
 
-!!! info
-    OpenAPI specifies that descriptions can be written in Markdown syntax, but the interactive documentation systems included still don't support it at the time of writing this, although they have it in their plans.
-
 ## Response description
 
 You can specify the response description with the parameter `response_description`:

diff --git a/fastapi/routing.py b/fastapi/routing.py
index a078662d868fc4d6272045f851fdf0417ec93b28..fe0ff6c2c0e067fb58072ffe348f0c399a37b243 100644 (file)
--- a/fastapi/routing.py
+++ b/fastapi/routing.py
@@ -137,7 +137,7 @@ class APIRoute(routing.Route):
         self.status_code = status_code
         self.tags = tags or []
         self.summary = summary
-        self.description = description or self.endpoint.__doc__
+        self.description = description or inspect.cleandoc(self.endpoint.__doc__ or "")
         self.response_description = response_description
         self.responses = responses or {}
         response_fields = {}

diff --git a/tests/test_tutorial/test_path_operation_configurations/test_tutorial005.py b/tests/test_tutorial/test_path_operation_configurations/test_tutorial005.py
index debe47a399e6ce00379370085c445525c3d61436..0cdb74249b302e12ae208b0ce926be8847924611 100644 (file)
--- a/tests/test_tutorial/test_path_operation_configurations/test_tutorial005.py
+++ b/tests/test_tutorial/test_path_operation_configurations/test_tutorial005.py
@@ -31,7 +31,7 @@ openapi_schema = {
                     },
                 },
                 "summary": "Create an item",
-                "description": "\n    Create an item with all the information:\n    \n    * name: each item must have a name\n    * description: a long description\n    * price: required\n    * tax: if the item doesn't have tax, you can omit this\n    * tags: a set of unique tag strings for this item\n    ",
+                "description": "Create an item with all the information:\n\n- **name**: each item must have a name\n- **description**: a long description\n- **price**: required\n- **tax**: if the item doesn't have tax, you can omit this\n- **tags**: a set of unique tag strings for this item",
                 "operationId": "create_item_items__post",
                 "requestBody": {
                     "content": {