harmbandstra/swagger-ui-bundle

Exposes swagger UI inside your Symfony project through a route (eg. /docs)

4.0.1 2018-12-10 18:47 UTC

README

Build Status Code Coverage

Swagger UI Bundle

Expose swagger-ui inside your symfony project through a route (eg. /docs), just like nelmio api docs, without the need for node.

Just add a reference to your swagger Yaml or JSON specification, and enjoy swagger-ui in all it's glory.

After installation and configuration, just start your local webserver, and navigate to /docs or /docs/my_swagger_spec.yml.

Compatibility

  • If you need symfony 2.3 - 2.6 support, use version 1.x.
  • If you need symfony 2.7 - 3.x support, or php 5.x use version 2.x.
  • For symfony 3.3 and later with PHP > 7.0 use version 3.x.
  • For symfony 4.0 and later with PHP => 7.1.3 use version 4.x.

NOTE Since version 3.1, support for symfony 4 on the 3.x branch has been dropped. Use the 4.x branch instead.

Installation

Install with composer in dev environment:

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

Make sure swagger-ui assets are copied to web/bundles by adding the HarmBandstra\SwaggerUiBundle\Composer\ScriptHandler::linkAssets composer hook before the Sensio\Bundle\DistributionBundle\Composer\ScriptHandler::installAssets hook in your composer.json.

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

Enable bundle in app/AppKernel.php(Symfony 3):

<?php

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

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

        // ...
    }
}

Enable bundle in config/bundles.php(Symfony 4):

<?php

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

Add the route where swagger-ui will be available in routing_dev.yml:

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

Configuration (Symfony 3)

In your config.yml, link to the swagger spec.

Specify the directory where your swagger files reside. You can access multiple files through the endpoint like /docs/my_swagger_spec.json. Under files you specify which files should be exposed.

The first file in the array is the default one and it will be the file the /docs endpoint will redirect to. For this file you have the option to specify an absolute path to the .json spec file ("/_swagger/swagger.json") or a 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"

Configuration (Symfony 4)

Create a file hb_swagger_ui.yaml in config/packages. Follow the rest of the steps for configuration in Symfony 3.