README

• About
• Install
• Usage
• Contributing

About

This bundle makes generating documentation of your (json) API routes easier. It provides a custom route annotation that can parse the input and output model of a route to generate documentation definitions for NelmioApiDocBundle. If you are using type hints for the input and output it can be detected automatically, see Usage on how to do this.

With just NelmioApiDocBundle you will often find yourself writing many annotations with a repetitive pattern. With this bundle common annotation combinations are bundled into one single route attribute.

This bundle can work well together with the http-kernel-bundle.

Install

Use composer to install the bundle from packagist.

composer require fusonic/api-documentation-bundle

Requirements:

• PHP 8.2+
• Symfony 5.4+

In case Symfony did not add the bundle to the bundle configuration, add the following (by default located in config/bundles.php):

<?php

return [
    // ...
    Fusonic\ApiDocumentationBundle\FusonicApiDocumentationBundle::class => ['all' => true],
];

Next you need to configure NelmioApiDocBundle.

There is one optional configuration for this bundle:

fusonic_api_documentation:
    # An attribute, class, or interface that is used to detect which object to parse the "input" model from.
    # If you do not configure this, automatic input detection will not work.
    request_object_class: Fusonic\ApiDocumentationBundle\Tests\App\FromRequest

Usage

Different examples can be found in the tests.

Example route with automatic type detection

If you have some kind of response listener that allows you to return objects directly from your controller then you can use the automatic output detection based on the return type or return annotation.

    #[DocumentedRoute(path: '/test-return-type/{id}', methods: ['GET'])]
    public function testReturnType(#[FromRequest] TestRequest $query): TestResponse
    {
        return new TestResponse($query->id);
    }

If you return an array or a generic type, you can set the return type (e.g.: SomeType[] or `SomeGeneric). The only requirement here is that you can only have one return type. Multiple return types are not supported.

Example route with manual input/output

If you do not support argument resolving and returning objects directly you can define the input and output classes manually.

    #[DocumentedRoute(path: '/test-return-type/{id}', methods: ['GET'], input: TestRequest::class, output: TestResponse::class)]
    public function testReturnType(int $id): JsonResponse
    {
    return new JsonResponse(['id' => $query->id], 200);
    }

You can also specify builtin types for the output, for example string:

#[DocumentedRoute(path: '/test-return-type/{id}', methods: ['GET'], input: TestRequest::class, output: 'string')]

If your manually defined output is a collection, you can set outputIsCollection: true in addition to the output:

#[DocumentedRoute(
    path: '/test-return-type/{id}',
    methods: ['GET'],
    input: TestRequest::class,
    description: 'custom description',
    statusCode: 200,
    output: 'string',
    outputIsCollection: true
)]

Documenting errors

Use the repeatable #[DocumentedError] attribute to document a route's error responses. Works on #[DocumentedRoute] and plain Symfony #[Route]:

#[DocumentedRoute(path: '/orders/{id}', methods: ['GET'])]
#[DocumentedError(exceptionClass: OrderNotFoundException::class, statusCode: 404)]
public function order(#[FromRequest] OrderRequest $request): OrderResponse

To document the error response body too, point the bundle at an exception method returning the context:

fusonic_api_documentation:
    exception_context_class:
        class: Fusonic\HttpKernelBundle\Exception\ContextAwareExceptionInterface
        method: getContext

The return type of getContext() is then used as the response schema.

Contributing

This is a subtree split of fusonic/php-extensions repository. Please create your pull requests there.