如何用zircote/swagger-php在ReDoc中排序API路径（OpenAPI/Symfony）

问题背景 #

使用zircote/swagger-php通过注解生成OpenAPI JSON文件时，paths节点的顺序随机，和注解定义顺序不一致，导致ReDoc按此无序结构展示API路径。尝试过ReDoc的sortOperationsAlphabetically、设置operationId、SortComponents处理器均未解决问题。

可行解决方案 #

方案一：生成后通过脚本排序JSON（最简单） #

直接在生成OpenAPI JSON后，用脚本对paths的键进行排序，无需修改swagger-php配置。

1. 编写PHP排序脚本（比如scripts/sort-openapi-paths.php）：

<?php
$jsonFile = __DIR__ . '/../doc/open-api.json';
$openapiData = json_decode(file_get_contents($jsonFile), true);

// 对paths的键按字母顺序排序
if (isset($openapiData['paths'])) {
    ksort($openapiData['paths']);
}

// 重新写入格式化后的JSON
file_put_contents(
    $jsonFile,
    json_encode($openapiData, JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES)
);

2. 集成到生成流程：
   在composer.json的scripts节点添加命令，把生成和排序步骤合并：

"scripts": {
    "openapi:generate": "bin/openapi -o doc/open-api.json --format json src && php scripts/sort-openapi-paths.php"
}

之后执行composer run openapi:generate即可生成已排序的OpenAPI文件。

方案二：自定义swagger-php处理器（集成到生成环节） #

针对swagger-php 3.3.3版本，自己实现一个处理器来排序paths，避免额外的脚本步骤。

1. 创建自定义处理器类：

<?php
namespace App\Swagger;

use OpenApi\Analysis;
use OpenApi\Processors\ProcessorInterface;

class SortPathsProcessor implements ProcessorInterface
{
    public function process(Analysis $analysis)
    {
        if (property_exists($analysis->openapi, 'paths') && !empty($analysis->openapi->paths)) {
            // 将paths转换为数组后排序，再赋值回去
            $paths = (array)$analysis->openapi->paths;
            ksort($paths);
            $analysis->openapi->paths = $paths;
        }

        return $analysis;
    }
}

2. 生成时指定处理器：
   执行生成命令时通过--processor参数加载自定义处理器：

bin/openapi -o doc/open-api.json --format json src --processor App\\Swagger\\SortPathsProcessor

确保类的命名空间符合项目的自动加载规则（比如PSR-4）。

方案三：ReDoc端配置（仅排序路径下的操作） #

如果只需要对单个路径下的HTTP操作（GET/POST/PUT等）排序，而非路径本身的顺序，可以使用ReDoc的sortOperationsAlphabetically配置：

• HTML标签方式：

<redoc spec-url="/doc/open-api.json" sort-operations-alphabetically></redoc>

• JS初始化方式：

Redoc.init('/doc/open-api.json', {
  sortOperationsAlphabetically: true
}, document.getElementById('redoc-container'));

注意：此配置仅对路径内的操作排序，无法改变路径本身的展示顺序。

内容的提问来源于stack exchange，提问作者NeyJâh