NelmioApiDocBundle 配置详解：打造完美的API文档系统-CSDN博客

NelmioApiDocBundle 配置详解：打造完美的API文档系统

前言

NelmioApiDocBundle 是 Symfony 生态中用于生成 API 文档的强大工具，它支持 OpenAPI/Swagger 规范，能够自动从你的代码中提取 API 信息并生成交互式文档。本文将深入解析该 Bundle 的配置选项，帮助你根据项目需求定制完美的 API 文档解决方案。

基础配置

所有配置都位于 nelmio_api_doc 键下。你可以通过以下命令查看配置：

# 查看默认配置值
php bin/console config:dump-reference nelmio_api_doc

# 查看实际使用的配置值
php bin/console debug:config nelmio_api_doc

核心配置项详解

1. 类型信息配置 (type_info)

类型: boolean
默认值: false

决定是否使用 Symfony 的 type-info 组件来确定类型。对于 Symfony 7.2 或更高版本的项目，建议设置为 true，这将显著提升类型检测的准确性。

2. 验证组配置 (use_validation_groups)

类型: boolean
默认值: false

当设置为 true 时，传递给 #[Model] 属性的 groups 将被用于限制验证约束。

3. 缓存配置 (cache)

类型: dictionary
允许键: pool, item_id

配置生成的文档缓存，提高性能：

nelmio_api_doc:
    cache:
        pool: 'cache.app'  # 使用的缓存池
        item_id: 'nelmio_api_doc_cache'  # 缓存项ID

4. 基础文档配置 (documentation)

类型: dictionary

设置 API 文档的基础信息，遵循 OpenAPI/Swagger 规范：

nelmio_api_doc:
    documentation:
        info:
            title: '我的应用'
            description: '我的应用描述'
            version: '1.0.0'

5. 媒体类型配置 (media_types)

类型: list
默认值: ['json']
允许值: json, xml

定义支持的媒体类型，如同时支持 JSON 和 XML：

nelmio_api_doc:
    media_types: ['json', 'xml']

6. UI 配置 (html_config)

类型: dictionary
允许键: assets_mode, swagger_ui_config, redocly_config, stoplight_config

配置文档界面的显示选项：

nelmio_api_doc:
    html_config:
        assets_mode: 'cdn'  # 或 'offline'
        swagger_ui_config:  # Swagger UI 特定配置
            docExpansion: 'none'
        redocly_config: {}  # ReDoc 特定配置
        stoplight_config: {}  # Stoplight Elements 配置

高级区域配置 (areas)

areas 配置允许你对路由进行筛选，只文档化特定的路由集合。

基本区域配置

nelmio_api_doc:
    areas:
        default:
            path_patterns:  # 路径匹配正则
                - ^/api
            host_patterns:  # 主机名匹配正则
                - ^api\.
            name_patterns:  # 路由名匹配正则
                - ^api_v1

区域特定配置

with_attribute: 是否只文档化带有 #[Areas] 注解/属性的路由
disable_default_routes: 是否禁用没有注解/属性的默认路由
documentation: 区域特定的基础文档配置
cache: 区域特定的缓存配置

模型配置 (models)

JMS 序列化器支持 (use_jms)

类型: boolean
默认值: false

是否使用 JMS Serializer 进行序列化。

模型别名配置 (names)

类型: list

定义模型别名或手动添加未被自动检测的模型：

nelmio_api_doc:
    models:
        names:
            -
                alias: 'UserPrivate'  # 文档中显示的别名
                type: 'App\Entity\User'  # 实际类名
                groups: ['private']  # 使用的序列化组