NelmioApiDocBundle

3.x version
Unmaintained
2.x

NelmioApiDocBundle

The NelmioApiDocBundle bundle allows you to generate documentation in the OpenAPI (Swagger) format and provides a sandbox to interactively browse the API documentation.

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 and the JMS serializer.

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

Note

If you're not using Flex, then add the bundle to your kernel:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
class AppKernel extends Kernel
{
    public function registerBundles()
    {
        $bundles = [
            // ...

            new Nelmio\ApiDocBundle\NelmioApiDocBundle(),
        ];

        // ...
    }
}

To browse your documentation with Swagger UI, register the following route:

1
2
3
4
5
# app/config/routing.yml
app.swagger_ui:
    path: /api/doc
    methods: GET
    defaults: { _controller: nelmio_api_doc.controller.swagger_ui }

If you also want to expose it in JSON, register this route:

1
2
3
4
5
# app/config/routing.yml
app.swagger:
    path: /api/doc.json
    methods: GET
    defaults: { _controller: nelmio_api_doc.controller.swagger }

As you just installed the bundle, you'll likely see routes you don't want in your documentation such as /_profiler/. To fix this, you can filter the routes that are documented by configuring the bundle:

1
2
3
4
5
# app/config/config.yml
nelmio_api_doc:
    areas:
        path_patterns: # an array of regexps
            - ^/api(?!/doc$)

New in version 3.1: The areas config option was added in version 3.1. You had to use routes in 3.0 instead.

How does this bundle work?

It generates you a swagger documentation from your symfony app thanks to Describers. Each of these Describers extract infos from various sources. For instance, one extract 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 Swagger specification to know the fields available):

1
2
3
4
5
6
nelmio_api_doc:
    documentation:
        info:
            title: My App
            description: This is an awesome app!
            version: 1.0.0

Note

If you're using Flex, this config is there by default. Don't forget to adapt it to your app!

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
namespace AppBundle\Controller;

use AppBundle\Entity\User;
use AppBundle\Entity\Reward;
use Nelmio\ApiDocBundle\Annotation\Model;
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",
     *         @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")
     */
    public function fetchUserRewardsAction(User $user)
    {
        // ...
    }
}

The normal PHP docblock for the controller method is used for the summary and description.

Use models

As shown in the example above, the bundle provides the @Model annotation. When you use it, the bundle will deduce your model properties.

Note

A model can be a Symfony form type, a Doctrine ORM entity or a general PHP object.

It 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"})
     * )
     */
    

Caution

The @Model annotation acts like a @Schema annotation. If you nest it with a @Schema annotation, the bundle will consider that you're documenting an array of models.

For instance, the following example:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
/**
 * @SWG\Response(
 *   response="200",
 *   description="Success",
 *   @SWG\Schema(@Model(type=User::class))
 * )
 */
public function getUserAction()
{
}

will produce:

1
2
3
4
5
# ...
responses:
    200:
        schema:
            items: { $ref: '#/definitions/User' }

while you probably expected:

1
2
3
4
# ...
responses:
    200:
        schema: { $ref: '#/definitions/User' }

To obtain the output you expected, remove the @Schema annotation:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
/**
 * @SWG\Response(
 *   response="200",
 *   description="Success",
 *   @Model(type=User::class)
 * )
 */
public function getUserAction()
{
}

If you're not using the JMS Serializer

The Symfony PropertyInfo component is used to describe your models. It supports doctrine annotations, type hints, and even PHP doc blocks as long as you required the phpdocumentor/reflection-docblock library. It does also support serialization groups when using the Symfony serializer.

If you're using the JMS Serializer

The metadata of the JMS serializer are used by default to describe your models. Additional information is extracted from the PHP doc block comment, but the property types must be specified in the JMS annotations.

In case you prefer using the Symfony PropertyInfo component (you won't be able to use JMS serialization groups), you can disable JMS serializer support in your config:

1
2
nelmio_api_doc:
    models: { use_jms: false }

Learn more

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

This work, including the code samples, is licensed under a Creative Commons BY-SA 3.0 license.