mirror of
https://github.com/retailcrm/NelmioApiDocBundle.git
synced 2025-02-02 23:59:26 +03:00
157 lines
4.0 KiB
Markdown
157 lines
4.0 KiB
Markdown
NelmioApiDocBundle
|
|
==================
|
|
|
|
[](http://travis-ci.org/nelmio/NelmioApiDocBundle)
|
|
[](https://packagist.org/packages/nelmio/api-doc-bundle)
|
|
[](https://packagist.org/packages/nelmio/api-doc-bundle)
|
|
|
|
The **NelmioApiDocBundle** bundle allows you to generate a decent documentation
|
|
for your APIs.
|
|
|
|
## Migrate from 2.x to 3.0
|
|
|
|
[To migrate from 2.x to 3.0, just follow our guide.](https://github.com/nelmio/NelmioApiDocBundle/blob/dev/UPGRADE-3.0.md)
|
|
|
|
## Installation
|
|
|
|
First, open a command console, enter your project directory and execute the following command to download the latest stable version of this bundle:
|
|
|
|
```
|
|
composer require nelmio/api-doc-bundle dev-dev
|
|
```
|
|
|
|
Then add the bundle to your kernel:
|
|
```php
|
|
class AppKernel extends Kernel
|
|
{
|
|
public function registerBundles()
|
|
{
|
|
$bundles = [
|
|
// ...
|
|
|
|
new Nelmio\ApiDocBundle\NelmioApiDocBundle(),
|
|
];
|
|
|
|
// ...
|
|
}
|
|
}
|
|
```
|
|
|
|
To access your documentation in your browser, register the following route:
|
|
|
|
```yml
|
|
# app/config/routing.yml
|
|
NelmioApiDocBundle:
|
|
resource: "@NelmioApiDocBundle/Resources/config/routing/swaggerui.xml"
|
|
prefix: /api/doc
|
|
```
|
|
|
|
## What does this bundle?
|
|
|
|
It generates you a swagger documentation from your symfony app thanks to
|
|
_Describers_. Each of this _Describers_ extract infos from various sources.
|
|
For instance, one extract data from SwaggerPHP annotations, one from your
|
|
routes, etc.
|
|
|
|
If you configured the route above, you can browse your documentation at
|
|
`http://example.org/api/doc`.
|
|
|
|
## Configure the bundle
|
|
|
|
If you just installed the bundle, you'll likely see routes you don't want in
|
|
your documentation such as `/_profiler/`.
|
|
To fix this, you can filter the routes that are documented by configuring the
|
|
bundle:
|
|
|
|
```yml
|
|
# app/config/config.yml
|
|
nelmio_api_doc:
|
|
routes:
|
|
path_patterns: # an array of regexps
|
|
- ^/api
|
|
```
|
|
|
|
## Use the bundle
|
|
|
|
You can configure globally your documentation in the config (take a look at
|
|
[the Swagger specification](http://swagger.io/specification/) to know the fields
|
|
available):
|
|
|
|
```yml
|
|
nelmio_api_doc:
|
|
documentation:
|
|
info:
|
|
title: My App
|
|
description: This is an awesome app!
|
|
version: 1.0.0
|
|
```
|
|
|
|
To document your routes, you can use annotations in your controllers:
|
|
|
|
```php
|
|
use AppBundle\Entity\User;
|
|
use AppBundle\Entity\Reward;
|
|
use Nelmio\ApiDocBundle\Annotation\Model;
|
|
use Sensio\Bundle\FrameworkExtraBundle\Configuration\Route;
|
|
use Swagger\Annotations as SWG;
|
|
|
|
class DefaultController
|
|
{
|
|
/*
|
|
* @Route("/api/{user}/rewards", methods={"GET"})
|
|
* @SWG\Response(
|
|
* response=200,
|
|
* description="Returns the rewards of an user",
|
|
* @SWG\Schema(
|
|
* type="array",
|
|
* @Model(type=Reward::class)
|
|
* )
|
|
* )
|
|
* @SWG\Parameter(
|
|
* name="order",
|
|
* in="query",
|
|
* type="string",
|
|
* description="The field used to order rewards"
|
|
* )
|
|
* @SWG\Tag(name="rewards")
|
|
*/
|
|
public function indexAction(User $user)
|
|
{
|
|
// ...
|
|
}
|
|
}
|
|
```
|
|
|
|
## What's supported?
|
|
|
|
This bundle supports _Symfony_ route requirements, PHP annotations,
|
|
[_Swagger-Php_](https://github.com/zircote/swagger-php) annotations,
|
|
[_FOSRestBundle_](https://github.com/FriendsOfSymfony/FOSRestBundle) annotations
|
|
and apps using [_Api-Platform_](https://github.com/api-platform/api-platform).
|
|
|
|
It supports models through the ``@Model`` annotation.
|
|
|
|
## Contributing
|
|
|
|
See
|
|
[CONTRIBUTING](https://github.com/nelmio/NelmioApiDocBundle/blob/master/CONTRIBUTING.md)
|
|
file.
|
|
|
|
## Running the Tests
|
|
|
|
Install the [Composer](http://getcomposer.org/) dependencies:
|
|
|
|
git clone https://github.com/nelmio/NelmioApiDocBundle.git
|
|
cd NelmioApiDocBundle
|
|
composer update
|
|
|
|
Then run the test suite:
|
|
|
|
./phpunit
|
|
|
|
## License
|
|
|
|
This bundle is released under the MIT license.
|