README

Swagger UI Bundle

通过路由（例如 /docs）在您的 symfony 项目中公开 swagger-ui，就像 nelmio api docs 一样，无需使用 node。

只需添加对您的 OpenAPI Yaml 或 JSON 规范的引用，即可享受所有的 swagger-ui。

安装和配置完成后，只需启动本地 web 服务器，然后导航到 /docs 或 /docs/my_swagger_spec.yml。

兼容性

• 如果您需要 symfony 2.3 - 2.6 支持，请使用版本 1.x。
• 如果您需要 symfony 2.7 - 3.x 支持，或 php 5.x，请使用版本 2.x。
• 对于 symfony 3.3 及以后的 PHP > 7.0，请使用版本 3.x。
• 对于 symfony 4.0 及以后的 PHP => 7.1.3，请使用版本 4.x。
• 对于 PHP > 8.0，请使用版本 > 4.4

注意 由于版本 3.1，3.x 分支已停止对 symfony 4 的支持。请使用 4.x 分支。

安装

在开发环境中使用 composer 安装

$ composer require harmbandstra/swagger-ui-bundle --dev

确保通过添加 HarmBandstra\SwaggerUiBundle\Composer\ScriptHandler::linkAssets composer 插件 在 Sensio\Bundle\DistributionBundle\Composer\ScriptHandler::installAssets 插件之前，将 swagger-ui 资产复制到 web/bundles。

{
  "scripts": {
    "symfony-scripts": [
        "HarmBandstra\\SwaggerUiBundle\\Composer\\ScriptHandler::linkAssets",
        "Sensio\\Bundle\\DistributionBundle\\Composer\\ScriptHandler::installAssets"
    ],
    "post-install-cmd": ["@symfony-scripts"],
    "post-update-cmd": ["@symfony-scripts"]
}

如果 composer.json 中的 scripts 部分如下（symfony 4）

    "scripts": {
        "auto-scripts": {
            "cache:clear": "symfony-cmd",
            "assets:install %PUBLIC_DIR%": "symfony-cmd"
        },
        "post-install-cmd": [
            "@auto-scripts"
        ],
        "post-update-cmd": [
            "@auto-scripts"
        ]
    },

添加 composer 插件如下

    "scripts": {
        "auto-scripts": {
            "cache:clear": "symfony-cmd",
            "assets:install %PUBLIC_DIR%": "symfony-cmd"
        },
        "post-install-cmd": [
            "HarmBandstra\\SwaggerUiBundle\\Composer\\ScriptHandler::linkAssets",
            "@auto-scripts"
        ],
        "post-update-cmd": [
            "HarmBandstra\\SwaggerUiBundle\\Composer\\ScriptHandler::linkAssets",
            "@auto-scripts"
        ]
    },

在 app/AppKernel.php（Symfony 3）中启用 bundle

<?php

class AppKernel extends Kernel
{
    public function registerBundles()
    {
        // ...

        if (in_array($this->getEnvironment(), ['dev', 'test'], true)) {
            // ...
            $bundles[] = new HarmBandstra\SwaggerUiBundle\HBSwaggerUiBundle();
        }

        // ...
    }
}

在 config/bundles.php（Symfony 4）中启用 bundle

<?php

return [
    // ...
    HarmBandstra\SwaggerUiBundle\HBSwaggerUiBundle::class => ['dev' => true]
];

在 routing_dev.yml 中添加 swagger-ui 可用的路由

_swagger-ui:
    resource: '@HBSwaggerUiBundle/Resources/config/routing.yml'
    prefix: /docs

配置（Symfony 3）

在您的 config.yml 中，链接到 swagger 规范。

指定您的 swagger 文件所在的 directory。您可以通过端点访问多个文件，例如 /docs/my_swagger_spec.json。在 files 中指定应公开哪些文件。

数组中的第一个文件是默认文件，它将是 /docs 端点重定向到的文件。对于此文件，您可以选择指定 .json 规范文件的绝对路径（"/_swagger/swagger.json"）或 URL（《https://example.com/swagger.json》）。

hb_swagger_ui:
  directory: "%kernel.root_dir%/../docs/"
  files:
    - "/_swagger/swagger.json"
    - "my_swagger_spec.yml"
    - "my_other_swagger_spec.json"

可选：如果您想为 Swagger UI 设置默认配置，请在 swagger 文件所在的同一目录中放置一个 config.json 文件，并将其添加到配置中。它将自动通过追加它作为查询参数 configUrl 加载。

hb_swagger_ui:
  configFile: "config.json"

可选：如果您从不同的目录提供服务项目，而不是从 vhost 根目录提供服务，则可以覆盖资产 URL 路径，使用 assetUrlPath 配置。确保添加一个开头和结尾的反斜杠。

hb_swagger_ui:
  assetUrlPath: '/my-vhost-sub-directory/bundles/hbswaggerui/'

配置（Symfony 4、5 和 6）

在 config/packages 中创建一个 hb_swagger_ui.yaml 文件。遵循在 Symfony 3 中配置的其余步骤。