Why every developer should care about API documentation

You may be thinking, “But nobody ever reads a manual; why would API documentation be any different?” I can guarantee that API documentation helps developers understand how to use your APIs and can improve the overall developer experience. In this article, we will discuss the importance of API documentation and how to use the NelmioApiDocBundle to generate documentation for your Symfony APIs.

API documentation should include a description of each endpoint, the parameters that can be passed to the endpoint, and the format of the response. This information helps developers understand what the API is capable of and how to use it effectively.

One tool that can help you generate API documentation for your Symfony application is the NelmioApiDocBundle. This bundle allows you to generate documentation for your APIs by parsing PHP annotations in your controllers.

How does Nelmio works ?

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

Installation

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

$ composer require nelmio/api-doc-bundle

This will install the NelmioApiDocBundle and add it to your project’s composer.json file.

Next, you will need to enable the bundle in your application. Open the config/bundles.php file and add the following line:

Nelmio\ApiDocBundle\NelmioApiDocBundle::class => ['all' => true]

This will enable the NelmioApiDocBundle in your application.

If you’re using Flex, this config is there by default under config/packages/nelmio_api_doc.yaml

nelmio_api_doc:
    documentation:
        servers:
          - url: http://api.example.com/unsafe
            description: API over HTTP
          - url: https://api.example.com/secured
            description: API over HTTPS
        info:
            title: My App
            description: This is an awesome app!
            version: 1.0.0
    areas: # to filter documented areas
        path_patterns:
            - ^/
        disable_default_routes: true

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

# config/routes.yaml
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:

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

Add a command in a doc.mk file to generate/update your API documentation:

generate-swagger:  ## Dump the swagger Open Api doc into a file
	docker exec -it ${PHP} bin/console nelmio:apidoc:dump --format=yaml > documentation/api/openapi.yml

To generate documentation for your APIs, you will need to add PHP annotations to your controllers. The NelmioApiDocBundle uses these annotations to generate the documentation.

/**
 * @Route("/users/{id}", methods={"GET"})
 * @param int $id
 * @return Response
 */
public function getUser(int $id): Response
{
    // ...
}

Use Models:

The bundle provides the @Model annotation. Use it instead of a definition reference and the bundle will deduce your model properties.

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

If you want to customize the documentation of an object’s property, you can use @OA\Property:

use Nelmio\ApiDocBundle\Annotation\Model;
use OpenApi\Annotations as OA;

class User
{
    /**
     * @var int
     * @OA\Property(description="The unique identifier of the user.")
     */
    public $id;
    /**
     * @OA\Property(type="string", maxLength=255)
     */
    public $name;
}

See the OpenAPI 3.0 specification to see all the available fields of @OA\Property.