PHPackages                             draw/open-api-bundle - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [API Development](/categories/api)
4. /
5. draw/open-api-bundle

ActiveSymfony-bundle[API Development](/categories/api)

draw/open-api-bundle
====================

draw/open-api library integration into Symfony4.

0.7.59(4y ago)010.1k1MITPHPPHP ^7.3CI failing

Since Apr 12Pushed 4y ago1 watchersCompare

[ Source](https://github.com/mpoiriert/open-api-bundle)[ Packagist](https://packagist.org/packages/draw/open-api-bundle)[ RSS](/packages/draw-open-api-bundle/feed)WikiDiscussions master Synced 6d ago

READMEChangelogDependencies (9)Versions (86)Used By (1)

Draw Open Api Bundle
====================

[](#draw-open-api-bundle)

Integration for draw/open-api into symfony 4 bundle

The first objective is to be able to generate a Open Api v2 documentation with minimum effort by the programmer. The draw/open-api provide a multitude of extractor to get the information where it can (PHP for example).

The integration with symfony allow you to use most of the **Draw\\Component\\OpenApi\\Schema** (alias @OpenApi) as annotation above your controller method to document them.

The bundle also provide some tools to provide a rest api without the need of FOSRestBundle.

Sandbox
-------

[](#sandbox)

To install the sandbox you can run

```
bin/console draw:open-api:install-sandbox
```

The first argument is the version to install (E.g.: v3.52.5). By default it master.

We recommend that you add this to your composer.json scripts section before the asset:install

```
{
    "scripts": {
            "auto-scripts": {
            "cache:clear": "symfony-cmd",
            "draw:open-api:install-sandbox": "symfony-cmd",
            "assets:install": "symfony-cmd"
        }
    }
}
```

Configuration
-------------

[](#configuration)

Here is a example of the configuration:

```
draw_open_api:
    enableDoctrineSupport: null #null will auto detect if DoctrineBundle is install and consider it true
    convertQueryParameterToAttribute: false
    responseConverter: false
    definitionAliases:
        - class: App\Entity\MyUser #This will change reference to class App\Entity\MyUser as User in the Api
          alias: User
        - class: App\Entity\ #This will Remove App\Entity\ from namespace so the class name would be expose instead of the FQCN
          alias: ''

    schema: #The schema section is not validate but it must match the Open Api format and will be the starting point of the generated doc
        info:
            title: 'Documentation for Acme API'
            description: 'This is the descriptoin of the 'Acme API'
            termsOfService: 'N\A'
            contact: ~
            version: "5.0"

```

Controller documentation
------------------------

[](#controller-documentation)

To document a controller for Open Api you must use the @OpenApi\\Tag or @OpenApi\\Operation annotations.

```
/**
 * @OpenApi\Tag("Acme")
 */
public function defaultAction()
{
   //...
}

```

```
/**
 * @OpenApi\Operation(
 *     operationId="default",
 *     tags={"Acme"}
 * )
 */
public function defaultAction()
{
   //...
}

```

If you plan to use the Open Api codegen we recommend using the @OpenApi\\Operation since it will give you control over the **operationId**, otherwise it will use the route name.

### Query Parameters

[](#query-parameters)

If you want to inject configured query parameters in a controller you must set the **convertQueryParameterToAttribute**to true in the configuration.

```
draw_open_api:
  convertQueryParameterToAttribute: true
```

You must also add the annotation **Draw\\Component\\OpenApi\\Schema\\QueryParameter** to your controller. This will provide the documentation information for Open Api and also configure which query parameters should be injected.

```
/**
 * @OpenApi\QueryParameter(name="param1")
 *
 * @param string $param1
 */
public function createAction($param1 = 'default')
{
   //...
}

```

### View

[](#view)

To allow the automatic serialization of response you must active it:

```
draw_open_api:
  responseConverter: true
```

The will detect if the return value of your controller is not a response and will serialized it according to the **Draw\\Bundle\\OpenApiBundle\\Response\\Serialization** annotation.

By default if there is not annotation the serializer context will not have any value and the response will be 200. Using the view allow to override the serializer groups and version, the status code of the response. The Serialization annotation is also use for the Open Api documentation, the headers attribute is use for that.

If your controller return null the status code will be set to 204 by default (not content).

```
/**
 * @Draw\Bundle\OpenApiBundle\Response\Serialization(
 *     statusCode=201,
 *     serializerGroups={"MyGroup"},
 *     headers={
 *       "X-Acme-CustomHeader"=@OpenApi\Header(type="string", description="The is a custom header")
 *     }
 * )
 */
public function createAction()
{
   //...
}

```

The **Draw\\Bundle\\OpenApiBundle\\Response\\Serialization** implement **Sensio\\Bundle\\FrameworkExtraBundle\\Configuration\\ConfigurationInterface**with a alias *draw\_open\_api\_serialization* `$request->attributes->get('_draw_open_api_serialization');`.

Instead of putting a **serializerVersion** on each header you can create a listener that will set the version base on something else. Here is a example of a listener that will take from the url path **/api/v{number}/....**:

```