Slim框架API路由展示Swagger遇500错误求助

核心问题 #

你遇到的两个关键错误点：

1. OpenApiGenerator::scan() 用法错误：这个方法是用来扫描PHP源代码中的注解生成OpenAPI规范，而非读取已生成的swagger.json文件。你混淆了「从代码生成规范」和「返回已生成的规范文件」两个逻辑。
2. 缺少全局OpenAPI基础注解：swagger-php要求必须存在@OA\OpenApi和@OA\Info这类全局注解，否则会抛出Required @OA\PathItem() not found错误，因为无法生成完整的OpenAPI结构。

分步解决 #

1. 修正/swagger路由逻辑

既然你已经通过openapi命令生成了swagger.json，直接读取该文件返回即可，无需再调用scan()方法：

use Slim\App;

// 假设swagger.json位于项目根目录，根据实际结构调整路径
$app->get('/swagger', function ($request, $response, $args) {
    $swaggerPath = __DIR__ . '/../swagger.json';
    
    if (!file_exists($swaggerPath)) {
        return $response->withStatus(404)->getBody()->write('Swagger specification file not found');
    }
    
    $swaggerContent = file_get_contents($swaggerPath);
    $response->getBody()->write($swaggerContent);
    return $response->withHeader('Content-Type', 'application/json');
});

2. 补充全局OpenAPI注解

在你的项目源码目录（比如src/下的任意PHP文件，建议新建Documentation.php）添加全局注解：

<?php
/**
 * @OA\OpenApi(
 *   @OA\Info(
 *     title="我的Slim RESTful API",
 *     version="1.0.0",
 *     description="基于Slim 4框架搭建的API服务"
 *   )
 * )
 */

3. 重新生成有效swagger.json

执行命令重新生成规范文件，确保注解被正确解析：

.\vendor\bin\openapi -output .\swagger.json .\src

4. （可选）添加Swagger UI访问路由

如果需要通过浏览器可视化查看API文档，添加一个返回Swagger UI页面的路由：

$app->get('/docs', function ($request, $response, $args) {
    $swaggerUiHtml = <<<HTML
<!DOCTYPE html>
<html lang="zh-CN">
<head>
    <meta charset="UTF-8">
    <title>API文档</title>
    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/swagger-ui-dist@5.11.0/swagger-ui.css" />
</head>
<body>
    <div id="swagger-ui"></div>
    <script src="https://cdn.jsdelivr.net/npm/swagger-ui-dist@5.11.0/swagger-ui-bundle.js"></script>
    <script src="https://cdn.jsdelivr.net/npm/swagger-ui-dist@5.11.0/swagger-ui-standalone-preset.js"></script>
    <script>
        window.onload = function() {
            SwaggerUIBundle({
                url: '/swagger',
                dom_id: '#swagger-ui',
                presets: [SwaggerUIBundle.presets.apis, SwaggerUIStandalonePreset],
                layout: "StandaloneLayout"
            });
        };
    </script>
</body>
</html>
HTML;
    $response->getBody()->write($swaggerUiHtml);
    return $response->withHeader('Content-Type', 'text/html');
});

额外注意点 #

• 确保你的API路由注解（比如@OA\Get）中的path参数和实际路由路径一致，否则生成的规范会出现路径不匹配问题。
• 可以用Swagger Editor打开生成的swagger.json，验证是否存在语法错误。

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