NelmioApiDocBundle - удобная документация для вашего REST Api
В процессе разработки Api наступает момент, когда методов становится слишком много и разобраться в них не представляется возможным.
Тогда нам на помощь приходит NelmioApiDocBundle. Этот инструмент дает нам возможность генерировать документацию, группировать и тестировать методы Api
1. Установка
$ composer require nelmio/api-doc-bundle:^3.0
В процессе установки будет предложено установить дополнительный пакет, я его себе поставил.
Symfony operations: 1 recipe (006d7495eb659c007cc228bbff3d71fd)
- WARNING nelmio/api-doc-bundle (>=3.0): From github.com/symfony/recipes-contrib:master
The recipe for this package comes from the "contrib" repository, which is open to community contributions.
Review the recipe at https://github.com/symfony/recipes-contrib/tree/master/nelmio/api-doc-bundle/3.0
Do you want to execute this recipe?
[y] Yes
[n] No
[a] Yes for all packages, only for the current installation session
[p] Yes permanently, never ask again for this project
(defaults to n): y
- Configuring nelmio/api-doc-bundle (>=3.0): From github.com/symfony/recipes-contrib:master
ocramius/package-versions: Generating version class...
ocramius/package-versions: ...done generating version class
2. Маршруты
Теперь нужно добавить новые маршруты в файл: config/routes.yaml
app.swagger_ui:
path: /api/doc
methods: GET
defaults: { _controller: nelmio_api_doc.controller.swagger_ui }
app.swagger:
path: /api/doc.json
methods: GET
defaults: { _controller: nelmio_api_doc.controller.swagger }
3. Вывод документации
Чтобы посмотреть сгенерированную документацию необходимо зайти по адресу: http://127.0.0.1:8000/api/doc
Вот что должно получиться в результате:
4. Группировка методов
Количество различных методов API возрастает с каждым днем, поэтому удобно разделить их на группы.
Выделим все методы управления новостями в группу "Новости".
Для этого необходимо использовать следущие аннотации
/**
* Получение списка последних новостей
* @SWG\Tag (name="Новости")
* @SWG\Response (
* response=200,
* description="Получение списка последних новостей"
* )
* @param Request $request
* @return View
*/
public function getAllAction(Request $request){
...
Теперь документация выглядит следующим образом:
