NelmioApiDocBundle

The NelmioApiDocBundle bundle allows you to generate a decent documentation for your APIs.

Migrate from 2.x to 3.0

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

Installation

First, open a command console, enter your project directory and execute the following command to download the latest version of this bundle (still in beta, for a stable version look here):

composer require nelmio/api-doc-bundle dev-master

Then add the bundle to your kernel:

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

            new Nelmio\ApiDocBundle\NelmioApiDocBundle(),
        ];

        // ...
    }
}

To access your documentation in your browser, register the following route:

# app/config/routing.yml
NelmioApiDocBundle:
    resource: "@NelmioApiDocBundle/Resources/config/routing/swaggerui.xml"
    prefix:   /api/doc

What does this bundle?

It generates you a swagger documentation from your symfony app thanks to Describers. Each of this Describers extract infos from various sources. For instance, one extract data from SwaggerPHP annotations, one from your routes, etc.

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

Configure the bundle

If 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:

# app/config/config.yml
nelmio_api_doc:
    routes:
        path_patterns: # an array of regexps
            - ^/api

Use the bundle

You can configure globally your documentation in the config (take a look at the Swagger specification to know the fields available):

nelmio_api_doc:
    documentation:
        info:
            title: My App
            description: This is an awesome app!
            version: 1.0.0

To document your routes, you can use annotations in your controllers:

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
{
    /*
     * @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)
    {
        // ...
    }
}

What's supported?

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

It supports models through the @Model annotation.

Contributing

See CONTRIBUTING file.

Running the Tests

Install the Composer dependencies:

git clone https://github.com/nelmio/NelmioApiDocBundle.git
cd NelmioApiDocBundle
composer update

Then run the test suite:

./phpunit

License

This bundle is released under the MIT license.

4.2 KiB Raw Blame History