diff --git a/docs/img/tutorial/path-operation-configuration/image02.png b/docs/img/tutorial/path-operation-configuration/image02.png
index 6315a2e0f..f4aee92ca 100644
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 4165745de..4a8758c59 100644
--- 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 Path Operation Configuration. PR #163.
+
* Upgrade Pydantic to version `0.23`. PR #160 by @euri10.
* Fix typo in Tutorial about Extra Models. PR #159 by @danielmichaels.
diff --git a/docs/src/path_operation_configuration/tutorial004.py b/docs/src/path_operation_configuration/tutorial004.py
index a4151a8cd..f47d422e0 100644
--- 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 f710e6c66..72d02ece3 100644
--- 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 ecbde5734..0808adec9 100644
--- 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 docstring and **FastAPI** will read it from there.
+You can write Markdown 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:
-!!! 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 a078662d8..fe0ff6c2c 100644
--- 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 debe47a39..0cdb74249 100644
--- 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": {