WARNING: You are browsing the documentation for version 2.x which is not maintained anymore. If some of your projects are still using this version, consider upgrading.

NelmioApiDocBundle

2.x version
Maintained

NelmioApiDocBundle

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

Installation

Step 1: Download the Bundle

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

1
$ composer require nelmio/api-doc-bundle

This command requires you to have Composer installed globally, as explained in the installation chapter of the Composer documentation.

Step 2: Enable the Bundle

Then, enable the bundle by adding it to the list of registered bundles in the app/AppKernel.php file of your project:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
<?php
// app/AppKernel.php

// ...
class AppKernel extends Kernel
{
    public function registerBundles()
    {
        $bundles = array(
            // ...
            new Nelmio\ApiDocBundle\NelmioApiDocBundle(),
        );

        // ...
    }

    // ...
}

Step 3: Register the Routes

Import the routing definition in routing.yml:

1
2
3
4
# app/config/routing.yml
NelmioApiDocBundle:
    resource: "@NelmioApiDocBundle/Resources/config/routing.yml"
    prefix:   /api/doc

Step 4: Configure the Bundle

Enable the bundle's configuration in app/config/config.yml:

1
2
# app/config/config.yml
nelmio_api_doc: ~

The NelmioApiDocBundle requires Twig as a template engine so do not forget to enable it:

1
2
3
4
# app/config/config.yml
framework:
    templating:
        engines: ['twig']

Usage

The main problem with documentation is to keep it up to date. That's why the NelmioApiDocBundle uses introspection a lot. Thanks to an annotation, it's really easy to document an API method. The following chapters will help you setup your API documentation:

Web Interface

You can browse the whole documentation at: http://example.org/api/doc.

_images/webview.png
_images/webview2.png

On-The-Fly Documentation

By calling an URL with the parameter ?_doc=1, you will get the corresponding documentation if available.

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