|
| 1 | +# fusonic-api-documentation-bundle |
| 2 | + |
| 3 | +[](https://github.com/fusonic/fusonic-api-documentation-bundle/blob/master/LICENSE) |
| 4 | +[](https://github.com/fusonic/fusonic-api-documentation-bundle/releases) |
| 5 | +[](https://packagist.org/packages/fusonic/fusonic-api-documentation-bundle) |
| 6 | + |
| 7 | + |
| 8 | +* [About](#about) |
| 9 | +* [Install](#install) |
| 10 | +* [Usage](#usage) |
| 11 | +* [Contributing](#contributing) |
| 12 | + |
| 13 | +## About |
| 14 | + |
| 15 | +This bundle makes generating documentation of your (json) API routes easier. It provides a custom route annotation that |
| 16 | +can parse the input and output model of a route to generate documentation definitions for |
| 17 | +[NelmioApiDocBundle](https://symfony.com/bundles/NelmioApiDocBundle/current/index.html). If you are using |
| 18 | +type hints for the input and output it can be detected automatically, see [Usage](#Usage) on how to do this. |
| 19 | + |
| 20 | +With just [NelmioApiDocBundle](https://symfony.com/bundles/NelmioApiDocBundle/current/index.html) you will often find yourself |
| 21 | +writing many annotations with a repetitive pattern. With this bundle common annotation combinations are bundled into one |
| 22 | +single route attribute. |
| 23 | + |
| 24 | +This bundle can work well together with |
| 25 | +the [http-kernel-extensions](https://github.com/fusonic/php-http-kernel-extensions). |
| 26 | + |
| 27 | +## Install |
| 28 | + |
| 29 | +Use composer to install the bundle from packagist. |
| 30 | + |
| 31 | +```bash |
| 32 | +composer require fusonic/fusonic-api-documentation-bundle |
| 33 | +``` |
| 34 | + |
| 35 | +Requirements: |
| 36 | + |
| 37 | +- PHP 8.1+ |
| 38 | +- Symfony 5.4+ |
| 39 | + |
| 40 | +In case Symfony did not add the bundle to the bundle configuration, add the following (by default located |
| 41 | +in `config/bundles.php`): |
| 42 | + |
| 43 | +``` |
| 44 | +<?php |
| 45 | +
|
| 46 | +return [ |
| 47 | + // ... |
| 48 | + Fusonic\ApiDocumentationBundle\FusonicApiDocumentationBundle::class => ['all' => true], |
| 49 | +]; |
| 50 | +``` |
| 51 | + |
| 52 | +Next you need to configure [NelmioApiDocBundle](https://symfony.com/bundles/NelmioApiDocBundle/current/index.html). |
| 53 | + |
| 54 | +There is one optional configuration for this bundle: |
| 55 | + |
| 56 | +```yaml |
| 57 | +fusonic_api_documentation: |
| 58 | + # An attribute, class, or interface that is used to detect which object to parse the "input" model from. |
| 59 | + # If you do not configure this, automatic input detection will not work. |
| 60 | + request_object_class: Fusonic\ApiDocumentationBundle\Tests\App\FromRequest |
| 61 | +``` |
| 62 | +
|
| 63 | +## Usage |
| 64 | +
|
| 65 | +Different examples can be found in the [tests](./tests/App/Controller/TestController.php). |
| 66 | +
|
| 67 | +#### Example route with automatic type detection |
| 68 | +
|
| 69 | +If you have some kind of response listener that allows you to return objects directly from your controller then you |
| 70 | +can use the automatic output detection based on the return type or return annotation. |
| 71 | +
|
| 72 | +```php |
| 73 | + #[DocumentedRoute(path: '/test-return-type/{id}', methods: ['GET'])] |
| 74 | + public function testReturnType(#[FromRequest] TestRequest $query): TestResponse |
| 75 | + { |
| 76 | + return new TestResponse($query->id); |
| 77 | + } |
| 78 | +``` |
| 79 | + |
| 80 | +If you return an array or a generic type, you can set the return type (e.g.: `SomeType[]` or `SomeGeneric<SomeType>). |
| 81 | +The only requirement here is that you can only have one return type. Multiple return types are not supported. |
| 82 | + |
| 83 | +#### Example route with manual input/output |
| 84 | + |
| 85 | +If you do not support argument resolving and returning objects directly you can define the `input` and `output` |
| 86 | +classes manually. |
| 87 | + |
| 88 | +```php |
| 89 | + #[DocumentedRoute(path: '/test-return-type/{id}', methods: ['GET'], input: TestRequest::class, output: TestResponse::class)] |
| 90 | + public function testReturnType(int $id): JsonResponse |
| 91 | + { |
| 92 | + return new JsonResponse(['id' => $query->id], 200); |
| 93 | + } |
| 94 | +``` |
| 95 | + |
| 96 | +You can also specify builtin types for the output, for example `string`: |
| 97 | + |
| 98 | +```php |
| 99 | +#[DocumentedRoute(path: '/test-return-type/{id}', methods: ['GET'], input: TestRequest::class, output: 'string')] |
| 100 | +``` |
| 101 | + |
| 102 | +If your manually defined output is a collection, you can set `outputIsCollection: true` in addition to the `output`: |
| 103 | + |
| 104 | +```php |
| 105 | +#[DocumentedRoute( |
| 106 | + path: '/test-return-type/{id}', |
| 107 | + methods: ['GET'], |
| 108 | + input: TestRequest::class, |
| 109 | + output: 'string', |
| 110 | + outputIsCollection: true |
| 111 | +)] |
| 112 | +``` |
| 113 | + |
| 114 | +## Contributing |
| 115 | + |
| 116 | +This is a subtree split of [fusonic/php-extensions](https://github.com/fusonic/php-extensions) repository. Please create |
| 117 | +your pull requests there. |
0 commit comments