{* ../../docs_src/path_operation_advanced_configuration/tutorial003_py310.py hl[6] *}

## Advanced description from docstring { #advanced-description-from-docstring }

You can limit the lines used from the docstring of a *path operation function* for OpenAPI.

Adding an `\f` (an escaped "form feed" character) causes **FastAPI** to truncate the output used for OpenAPI at this point.

## Description from docstring { #description-from-docstring }

As descriptions tend to be long and cover multiple lines, you can declare the *path operation* description in the function <dfn title="a multi-line string as the first expression inside a function (not assigned to any variable) used for documentation">docstring</dfn> and **FastAPI** will read it from there.

{* ../../docs_src/path_operation_configuration/tutorial003_py310.py hl[17:18] *}

## 從 docstring 取得描述 { #description-from-docstring }

由於描述常常較長、跨越多行，你可以在函式的 <dfn title="用於文件的多行字串，作為函式內的第一個運算式（不賦值給任何變數）">文件字串（docstring）</dfn> 中宣告「路徑操作」的描述，**FastAPI** 會從那裡讀取。

你可以在 docstring 中書寫 [Markdown](https://en.wikipedia.org/wiki/Markdown)，它會被正確解析並顯示（會考慮 docstring 的縮排）。

{* ../../docs_src/path_operation_configuration/tutorial004_py310.py hl[17:25] *}

## docstringを用いた説明 { #description-from-docstring }

説明文は長くて複数行におよぶ傾向があるので、関数<dfn title="関数内の最初の式（どの変数にも代入されない）として記述される、ドキュメント用の複数行の文字列">docstring</dfn>内に*path operation*の説明文を宣言できます。すると、**FastAPI** は説明文を読み込んでくれます。

docstringに[Markdown](https://en.wikipedia.org/wiki/Markdown)を記述すれば、正しく解釈されて表示されます。（docstringのインデントを考慮して）

def client_fixture() -> TestClient:
    from pydantic import BaseModel

    class Address(BaseModel):
        """
        This is a public description of an Address
        \f
        You can't see this part of the docstring, it's private!
        """

        line_1: str
        city: str
        state_province: str

    class Facility(BaseModel):
        id: str
        address: Address

    app = FastAPI()

若要從產生的 OpenAPI 結構（也就是自動文件系統）中排除某個*路徑操作*，使用參數 `include_in_schema` 並將其設為 `False`：

{* ../../docs_src/path_operation_advanced_configuration/tutorial003_py310.py hl[6] *}

## 從 docstring 提供進階描述 { #advanced-description-from-docstring }

你可以限制 OpenAPI 從*路徑操作函式*的 docstring 中使用的內容行數。

加上一個 `\f`（跳頁字元，form feed）會讓 FastAPI 在此處截斷用於 OpenAPI 的輸出。

這個字元不會出現在文件中，但其他工具（例如 Sphinx）仍可使用其後的內容。

使用参数 `include_in_schema` 并将其设置为 `False`，来从生成的 OpenAPI 方案中排除一个 *路径操作*（这样一来，就从自动化文档系统中排除掉了）：

{* ../../docs_src/path_operation_advanced_configuration/tutorial003_py310.py hl[6] *}

## 来自 docstring 的高级描述 { #advanced-description-from-docstring }

你可以限制 *路径操作函数* 的 `docstring` 中用于 OpenAPI 的行数。

添加一个 `\f`（一个“换页”的转义字符）可以使 **FastAPI** 在那一位置截断用于 OpenAPI 的输出。

剩余部分不会出现在文档中，但是其他工具（比如 Sphinx）可以使用剩余部分。

{* ../../docs_src/path_operation_advanced_configuration/tutorial003_py310.py hl[6] *}

## docstringによる説明の高度な設定 { #advanced-description-from-docstring }

*path operation関数* のdocstringからOpenAPIに使用する行を制限できます。

`\f`（エスケープされた「書式送り（form feed）」文字）を追加すると、**FastAPI** はその地点でOpenAPIに使用される出力を切り詰めます。

ドキュメントには表示されませんが、他のツール（Sphinxなど）は残りの部分を利用できます。

{* ../../docs_src/path_operation_advanced_configuration/tutorial003_py310.py hl[6] *}

## docstring에서 고급 설명 가져오기 { #advanced-description-from-docstring }

OpenAPI에 사용할 *경로 처리 함수*의 docstring 줄 수를 제한할 수 있습니다.

`\f`(이스케이프된 "form feed" 문자)를 추가하면 **FastAPI**는 이 지점에서 OpenAPI에 사용할 출력 내용을 잘라냅니다.

문서에는 표시되지 않지만, Sphinx 같은 다른 도구는 나머지 부분을 사용할 수 있습니다.

        final String docString = getXmlString(document);
        final String pnString = getXmlString(pruneNode);
        assertTrue(docString.contains("<SCRIPT>"));
        assertTrue(docString.contains("foo"));
        assertTrue(docString.contains("<NOSCRIPT>"));
        assertTrue(docString.contains("bar"));
        assertTrue(pnString.contains("<SCRIPT>"));