NelmioApiDocBundle

What's supported?

This bundle supports Symfony route requirements, PHP annotations, Swagger-Php annotations, FOSRestBundle annotations and apps using Api-Platform.

For models, it supports the Symfony serializer , the JMS serializer and the willdurand/Hateoas library. It does also support Symfony form types.

Migrate from 2.x to 3.0

To migrate from 2.x to 3.0, follow our guide.

Installation

Open a command console, enter your project directory and execute the following command to download the latest version of this bundle:

1

$ composer require nelmio/api-doc-bundle:^3.0

1
2
3
4
5
6
7
8
9
10
11
12
13

class AppKernel extends Kernel
{
    public function registerBundles(): iterable
    {
        $bundles = [
            // ...

            new Nelmio\ApiDocBundle\NelmioApiDocBundle(),
        ];

        // ...
    }
}

1
2
3
4
5

# config/routes.yaml
app.swagger_ui:
    path: /api/doc
    methods: GET
    defaults: { _controller: nelmio_api_doc.controller.swagger_ui }

1
2
3
4
5

# config/routes.yaml
app.swagger:
    path: /api/doc.json
    methods: GET
    defaults: { _controller: nelmio_api_doc.controller.swagger }

1
2
3
4
5
6
7

# config/packages/nelmio_api_doc.yaml
nelmio_api_doc:
    areas:
        path_patterns: # an array of regexps
            - ^/api(?!/doc$)
        host_patterns:
            - ^api\.

How does this bundle work?

It generates an OpenAPI documentation from your Symfony app thanks to Describers. One extracts data from SwaggerPHP annotations, one from your routes, etc.

If you configured the app.swagger_ui route above, you can browse your documentation at `http://example.org/api/doc`.

Using the bundle

You can configure global information in the bundle configuration documentation.info section (take a look at the OpenAPI 2.0 specification (formerly Swagger) to know the available fields):

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

nelmio_api_doc:
    documentation:
        host: api.example.com
        schemes: [http, https]
        info:
            title: My App
            description: This is an awesome app!
            version: 1.0.0
        securityDefinitions:
            Bearer:
                type: apiKey
                description: 'Value: Bearer {jwt}'
                name: Authorization
                in: header
        security:
            - Bearer: []

To document your routes, you can use the SwaggerPHP annotations and the Nelmio\ApiDocBundle\Annotation\Model annotation in your controllers:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39

namespace AppBundle\Controller;

use AppBundle\Entity\User;
use AppBundle\Entity\Reward;
use Nelmio\ApiDocBundle\Annotation\Model;
use Nelmio\ApiDocBundle\Annotation\Security;
use Swagger\Annotations as SWG;
use Symfony\Component\Routing\Annotation\Route;

class UserController
{
    /**
     * List the rewards of the specified user.
     *
     * This call takes into account all confirmed awards, but not pending or refused awards.
     *
     * @Route("/api/{user}/rewards", methods={"GET"})
     * @SWG\Response(
     *     response=200,
     *     description="Returns the rewards of an user",
     *     @SWG\Schema(
     *         type="array",
     *         @SWG\Items(ref=@Model(type=Reward::class, groups={"full"}))
     *     )
     * )
     * @SWG\Parameter(
     *     name="order",
     *     in="query",
     *     type="string",
     *     description="The field used to order rewards"
     * )
     * @SWG\Tag(name="rewards")
     * @Security(name="Bearer")
     */
    public function fetchUserRewardsAction(User $user)
    {
        // ...
    }
}

The normal PHPdoc block on the controller method is used for the summary and description.

Use models

As shown in the example above, the bundle provides the @Model annotation. Use it instead of a definition reference and the bundle will deduce your model properties.

This annotation has two options:

• type to specify your model's type:

  1
  2
  3
  4
  5
  6

  /**
   * @SWG\Response(
   *     response=200,
   *     @Model(type=User::class)
   * )
   */

• groups to specify the serialization groups used to (de)serialize your model:

  1
  2
  3
  4
  5
  6

  /**
   * @SWG\Response(
   *     response=200,
   *     @Model(type=User::class, groups={"non_sensitive_data"})
   * )
   */

1
2
3
4
5
6
7
8
9
10
11
12
13

/**
 * @SWG\Response(
 *     @SWG\Schema(ref=@Model(type=User::class))
 * )
 *
 * or
 *
 * @SWG\Response(
 *     @SWG\Schema(type="object",
 *         @SWG\Property(property="foo", ref=@Model(type=FooClass::class))
 *     )
 * )
 */

1
2
3
4
5
6

$builder->add('username', TextType::class, [
    'documentation' => [
        'type' => 'string', // would have been automatically detected in this case
        'description' => 'Your username.',
    ],
]);

1
2

nelmio_api_doc:
    models: { use_jms: false }

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

use Nelmio\ApiDocBundle\Annotation\Model;
use Swagger\Annotations as SWG;

class User
{
    /**
     * @var int
     * @SWG\Property(description="The unique identifier of the user.")
     */
    public $id;

    /**
     * @SWG\Property(type="string", maxLength=255)
     */
    public $username;

    /**
     * @SWG\Property(ref=@Model(type=User::class))
     */
    public $friend;
}

Learn more

If you need more complex features, take a look at: