如何让mkdocs自动识别Pydantic BaseModel字段信息生成文档？

可以通过mkdocstrings插件实现自动从Pydantic模型的Field参数中提取字段描述、类型和默认值，无需手动在文档字符串中重复编写冗余内容。具体步骤如下：

1. 安装依赖 #

安装支持Python解析的mkdocstrings插件：

pip install mkdocstrings[python]

2. 配置MkDocs #

在项目根目录的mkdocs.yml中添加插件配置，指定优先使用Pydantic的字段信息，关闭手动编写的参数和类型说明：

plugins:
  - mkdocstrings:
      default_handler: python
      handlers:
        python:
          # 如果你的代码在src等子目录，添加路径让插件能找到模块
          paths: [src]
          options:
            show_signature: true
            show_signature_annotations: true
            # 关闭文档字符串中手动写的:param和:type，避免重复
            show_docstring_parameters: false
            show_docstring_types: false
            members_order: source

3. 简化Pydantic模型文档字符串 #

删除文档字符串中冗余的:param和:type部分，只保留类的核心描述：

from pydantic import BaseModel, Field

class MyModel(BaseModel):
    """This text is good."""

    field_1: int = Field(default=3, description="description of field_1")

4. 在文档中引用模型 #

在你的Markdown文档中，使用:::指令引用目标模型，插件会自动渲染模型的类描述、字段类型、默认值和描述：

::: your_module_name.MyModel

配置完成后，构建MkDocs文档时，插件会直接从Pydantic的Field参数中提取所有字段信息，生成清晰的模型文档，无需手动维护冗余内容。

内容的提问来源于stack exchange，提问作者mohamed martini