Developed with love by KnpLabs Hire us for your project!
48

swagger-bundle

by MeredithCorpOSS

PHP Symfony bundle for implementing Swagger

SwaggerBundle

Travis
Packagist

This bundle provides integration of swagger-php in Symfony.
It should only run in the dev environment, as searching for annotations at runtime is not performant. The bundle comes
with the ability to generate a swagger.json file that can be statically served.

Installation

Install via Composer:
bash
composer require timeinc/swagger-bundle --dev

Enable Bundle

In your app/AppKernel.php file, add the following to your list of dev bundles:
```php
<?php

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

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

    // ...
}

}


## Configure Bundle

### Application Configuration
Open `./app/config/config_dev.yml` and add your configuration like below.

```yaml
swagger:
    version: '2.0'
    info:
        title: 'My API'
        version: '1.0.0'
        description: 'My API Description'
    host: 'my-api-host:8080'
    base_path: '/v2'
    schemes:
        - https
    alternative_hosts:
        - { name: 'production', host: 'productionhost', schemes: [https], base_path: '/api' }
    produces:
        - application/json
    consumes:
        - application/json
    annotations:
        bundles:
            - AcmeDemoBundle
    pretty_json: true

The full configuration reference for a comprehensive list of all values and defaults.

Routing

The bundle comes with routes to view the default swagger.json schema or schemas with overridden host, schemes and base_path as defined by your presets. To enable the routes, add the following to your
./app/config/routing_dev.yml:

_swagger:
    resource: "@SwaggerBundle/Resources/config/routing.xml"
    prefix:   /

You can then access your default schema through /_swagger/swagger.json or your alternative schemas through /_swagger/swagger-{alternative-host-name}.json. As noted before, this should not be added to the
production routes.

Usage

Once you have registered your bundles under swagger > bundles in config_dev.yml, the swagger-bundle will
automatically search for any swagger-php annotations under:

  • [bundle_dir]/Controller
  • [bundle_dir]/Document
  • [bundle_dir]/Entity
  • [bundle_dir]/Form
  • [bundle_dir]/Model
  • [bundle_dir]/Swagger

Please see swagger-php's annotation reference
for details about swagger-php's syntax.

Symfony Routes

This bundle comes with an extra \TimeInc\SwaggerBundle\Swagger\Annotation\Route annotation that allows you to define
a symfony route as a swagger endpoint. using the annotation will set a swagger path for each method and add parameters
for the path variables and any defaults as query strings.

The annotation can be defined on a class or a method with the following properies:

Property Context Default Notes
method CLASS The method name to inspect
route CLASS\ METHOD
returns CLASS\ METHOD entity
entity CLASS\ METHOD
queryParams CLASS\ METHOD []
headers CLASS\ METHOD []

NOTE: If the entity is omitted, the bundle will search for an entity name of the same name as the controller in the
same bundle. For Example, the below example controller is Acme\PetBundle\Controller\PetController, so the bundle
will search for an entity in Acme\PetBundle\Entity\Pet

<?php

namespace Acme\PetBundle\Controller;

use TimeInc\SwaggerBundle\Swagger\Annotation\Route;

/**
 * @Route(
 *     method="cgetAction",
 *     route="api_get_pets",
 *     returns="collection"
 * )
 */
class PetController
{
    /**
     * This annotation defines no entity. The bundle will check an entity exists in:
     *     Acme\PetBundle\Entity\Pet
     * 
     * @Route(
     *     route="api_get_pet"
     * )
     */
    public function getAction()
    {}

    /**
     * @Route(
     *     route="api_get_pet_owner",
     *     entity="Acme\PetBundle\Entity\Owner",
     *     headers={"X-TEST": "string"},
     *     queryParams={"query": "string", "page": "integer"}
     * )
     */
    public function getOwnerAction()
    {}   
}

Command Line

You can dump the json schema to the console with the swagger:dump command:

./bin/console -e=dev swagger:dump --pretty

HINT: You can use the option --alternative-host=product to override host, schemes and base_path with your production preset

API Gateway

The bundle can also generate a swagger schema for an
AWS API Gateway using the HTTP
Proxy.

The schema can then be imported into the AWS console to generate a 1-1
route mapping over a HTTP proxy for your API. All parameters and headers
and imported into AWS and passed through.

API Gateway

Please see the docs on how to integrate your API with API Gateway.

  • Fixed annotation registry function (#23)
    By web-flow, 3 years ago
  • Corrected config reference in readme (#20)
    By web-flow, 3 years ago
  • Added support for alternative hosts and pretty JSON output. (#18)
    By andythorne, 3 years ago
  • Fixed Build icon in readme (#15)
    By web-flow, 4 years ago
  • Updated test to account for symfony versions (#14)
    By web-flow, 4 years ago
  • Updated API Gateway integration for proxy passthrough (#12)
    By web-flow, 4 years ago
  • Make the SwaggerController compatible with Syfony 3.0 and lower (#9)
    By andythorne, 4 years ago
  • Fixed parameter format (#7)
    By web-flow, 4 years ago
  • Fix composer.json (#4)
    By andythorne, 4 years ago
  • Added required items key to array parameters (#6)
    By web-flow, 4 years ago
  • Merge pull request #5 from hipio/patch-1
    By web-flow, 4 years ago
  • FIx: Bad config
    By web-flow, 4 years ago
  • Merge pull request #3 from andythorne/query-vars
    By web-flow, 4 years ago
  • Fixed php7 only code
    By andythorne, 4 years ago
  • Added query and header options to route annotation
    By andythorne, 4 years ago
  • Added tests
    By andythorne, 4 years ago
  • Added query parameter mapping from route defaults
    By andythorne, 4 years ago
  • Merge pull request #2 from andythorne/api-gateway
    By web-flow, 4 years ago
  • Added more readme docs
    By andythorne, 4 years ago
  • Added responseParameters for API Gateway
    By andythorne, 4 years ago
  • Merge pull request #1 from andythorne/api-gateway
    By web-flow, 4 years ago
  • Api Gateway schema exports
    By andythorne, 4 years ago
  • Don't return 405 response as default response
    By andythorne, 4 years ago
  • Allow route to be defined as single parameter
    By andythorne, 4 years ago
  • Added base swagger options to config.yml
    By andythorne, 4 years ago
  • Tell json response data is already encoded
    By andythorne, 4 years ago
  • Fixed builds for PHP 5.x
    By andythorne, 4 years ago
  • Initial Commit
    By andythorne, 4 years ago