Symfony4项目：如何用NelmioApiDocBundle3在构建流水线生成静态API文档？

算力阿峰

2026-5-21

关于NelmioApiDocBundle 3.x生成静态API文档的解决方案

首先明确一点：你没遗漏任何东西——NelmioApiDocBundle 3.x确实移除了v2版本里自带的静态文档生成命令，官方在升级时选择把这个功能剥离，转而让开发者借助标准的OpenAPI工具链来实现静态导出，这样更贴合整个API文档生态的标准流程。

下面给你几个在构建流水线（比如Bitbucket Pipelines）里可行的实现方案：

方案一：用OpenAPI规范+第三方工具生成静态HTML

这是最推荐的方式，因为NelmioApiDocBundle本质是生成符合OpenAPI规范的JSON/YAML文件，我们只需要拿到这个文件，再用成熟的工具转成静态页面即可：

获取OpenAPI规范文件
在构建流水线中，用curl访问你的应用的API文档端点（默认是/api/doc.json或/api/doc.yaml），把规范文件保存到本地：
```
# 示例：如果是测试环境的地址
curl https://your-test-app.com/api/doc.json -o openapi-spec.json
```
如果是在本地构建或者容器内构建，就用对应的内部地址（比如http://localhost/api/doc.json）。
用工具生成静态HTML
推荐使用redoc-cli（生成的文档美观且响应式），或者swagger-ui-dist：
- 先安装依赖（如果是Bitbucket Pipelines，可以在bitbucket-pipelines.yml里添加npm安装步骤）：
```
npm install -g redoc-cli
```
- 生成静态HTML文件：
```
redoc-cli bundle openapi-spec.json -o static-api-docs.html
```
生成的static-api-docs.html就是纯静态的，可以直接上传到静态托管服务、归档或者作为构建产物保存。

方案二：自定义Symfony命令生成规范文件

如果你希望完全在Symfony生态内完成第一步的规范生成，可以自己写一个简单的命令来获取ApiDocGenerator的输出：

创建自定义命令
在你的Symfony项目中新建一个命令类：

// src/Command/ExportApiDocCommand.php
namespace App\Command;

use Symfony\Component\Console\Command\Command;
use Symfony\Component\Console\Input\InputInterface;
use Symfony\Component\Console\Output\OutputInterface;
use Nelmio\ApiDocBundle\ApiDocGeneratorInterface;
use Symfony\Component\Serializer\SerializerInterface;

class ExportApiDocCommand extends Command
{
    protected static $defaultName = 'app:export-api-doc';

    public function __construct(
        private readonly ApiDocGeneratorInterface $apiDocGenerator,
        private readonly SerializerInterface $serializer
    ) {
        parent::__construct();
    }

    protected function execute(InputInterface $input, OutputInterface $output): int
    {
        // 生成OpenAPI规范对象
        $openApi = $this->apiDocGenerator->generate();
        
        // 序列化为JSON格式
        $jsonContent = $this->serializer->serialize(
            $openApi,
            'json',
            ['openapi_spec' => true]
        );
        
        // 保存到项目目录（可根据需求修改路径）
        file_put_contents(__DIR__.'/../../openapi-spec.json', $jsonContent);
        
        $output->writeln('✅ OpenAPI规范文件已成功导出！');
        return Command::SUCCESS;
    }
}

在流水线中调用命令
在Bitbucket Pipelines的配置里，先运行Symfony命令导出规范，再用redoc-cli生成静态页面：

# bitbucket-pipelines.yml 示例片段
script:
  - php bin/console app:export-api-doc
  - npm install -g redoc-cli
  - redoc-cli bundle openapi-spec.json -o static-api-docs.html
  # 后续可以添加上传或归档步骤

补充说明

官方移除内置命令的核心原因是：OpenAPI生态已经有非常成熟的静态生成工具，把这个功能交给专业工具处理，能让NelmioApiDocBundle更专注于动态API文档的渲染和规范生成。上面的两种方案都能完美适配构建流水线的自动化需求，而且灵活性比旧版本的内置命令更高。

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

Symfony4项目：如何用NelmioApiDocBundle3在构建流水线生成静态API文档？

方案一：用OpenAPI规范+第三方工具生成静态HTML #

方案二：自定义Symfony命令生成规范文件 #

补充说明 #

方案一：用OpenAPI规范+第三方工具生成静态HTML

方案二：自定义Symfony命令生成规范文件

补充说明