✨ Upgrade docstring Markdown parsing (#163)

* ✨ Upgrade docstring Markdown parsing

* 📝 Update release notes

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>.

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
+    - **name**: each item must have a name
-    * description: a long description
+    - **description**: a long description
-    * price: required
+    - **price**: required
-    * tax: if the item doesn't have tax, you can omit this
+    - **tax**: if the item doesn't have tax, you can omit this
-    * tags: a set of unique tag strings for this item
+    - **tags**: a set of unique tag strings for this item
     """
     return item

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
+    - **name**: each item must have a name
-    * description: a long description
+    - **description**: a long description
-    * price: required
+    - **price**: required
-    * tax: if the item doesn't have tax, you can omit this
+    - **tax**: if the item doesn't have tax, you can omit this
-    * tags: a set of unique tag strings for this item
+    - **tags**: a set of unique tag strings for this item
     """
     return item

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`:

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 = {}

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": {