自动文档（Auto-documentation）

为了更容易地记录响应函数，Sanic 拓展将使用函数的文档字符串来填充您的文档。

总结和描述（Summary and description）

函数的文档字符串将用于创建摘要和描述。从这个例子中可以看出，文档字符串已经被解析，使用第一行作为摘要，字符串的剩余部分作为描述。

@app.get("/foo")
async def handler(request, something: str):
    """This is a simple foo handler
    It is helpful to know that you could also use **markdown** inside your
    docstrings.
    - one
    - two
    - three"""
    return text(">>>")

{
  "paths": {
    "/foo": {
      "get": {
        "summary": "This is a simple foo handler",
        "description": "It is helpful to know that you could also use **markdown** inside your<br>docstrings.<br><br>- one<br>- two<br>- three",
        "responses": {
          "default": {
            "description": "OK"
          }
        },
        "operationId": "get_handler"
      }
    }
  }
}

YAML 级操作（Operation level YAML）

您可以通过在文档字符串中添加有效的 OpenAPI YAML 来对此进行扩展。只需添加一行包含 openapi: 的内容，后跟您的 YAML。

示例中显示的 --- 不是必需的。它只是在那里帮助视觉识别 YAML 作为文档字符串的一个独特部分。

@app.get("/foo")
async def handler(request, something: str):
    """This is a simple foo handler
    Now we will add some more details
    openapi:
    ---
    operationId: fooDots
    tags:
      - one
      - two
    parameters:
      - name: limit
        in: query
        description: How many items to return at one time (max 100)
        required: false
        schema:
          type: integer
          format: int32
    responses:
      '200':
        description: Just some dots
    """
    return text("...")

{
  "paths": {
    "/foo": {
      "get": {
        "operationId": "fooDots",
        "summary": "This is a simple foo handler",
        "description": "Now we will add some more details",
        "tags": [
          "one",
          "two"
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "description": "How many items to return at one time (max 100)",
            "required": false,
            "schema": {
              "type": "integer",
              "format": "int32"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Just some dots"
          }
        }
      }
    }
  }
}

小提示

当 YAML 文档和装饰器都被使用时，在生成文档时将优先使用装饰器中的内容。

排除文档字符串（Excluding docstrings）

有时，函数的文档字符串中可能包含并不打算展示在文档中的字符串。

选项 1: 在配置文件中设置 app.config.OAS_AUTODOC = False 禁用整个项目的文档自动生成功能

选项 2: 使用 @openapi.no_autodoc 装饰器为某个指定的响应程序禁用自动文档生成功能。

@app.get("/foo")
@openapi.no_autodoc
async def handler(request, something: str):
    """This is a docstring about internal info only. Do not parse it.
    """
    return text("...")