NelmioApiDocBundle/Resources/doc/index.md

NelmioApiDocBundle

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

• Installation
• Usage
  • The ApiDoc() Annotation
  • Multiple API Documentation a.k.a. "Views"
  • Other Bundle Annotations
  • Swagger Support
  • DunglasApiBundle Support
  • Sandbox
  • Commands
• Configuration In-Depth
• Frequently Asked Questions
• Configuration Reference

Installation

Require the nelmio/api-doc-bundle package in your composer.json and update your dependencies.

$ composer require nelmio/api-doc-bundle

Register the bundle in app/AppKernel.php:

// app/AppKernel.php
public function registerBundles()
{
    return array(
        // ...
        new Nelmio\ApiDocBundle\NelmioApiDocBundle(),
    );
}

Import the routing definition in routing.yml:

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

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

# app/config/config.yml
nelmio_api_doc: ~

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

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

• The ApiDoc() Annotation
• Multiple API Documentation a.k.a. "Views"
• Other Bundle Annotations
• Swagger Support
• DunglasApiBundle Support
• Sandbox
• Commands

Web Interface

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

On-The-Fly Documentation

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