Прежде чем писать эту статью, я пытался найти что-то подобное, и, возможно, в силу каких-то обстоятельств, так и не нашел.
Я решил изложить свое видение этого вопроса.
Откуда взялась идея? За последние несколько лет я сменил 3-4 компании, в которых получил мягко говоря лапшу, толстые контроллеры и минимум аннотаций.
Трудно сказать, с чем именно связано отсутствие аннотаций; возможно, это простая лень или незнание того, что аннотации позволяют описывать больше, чем просто входные параметры классов/методов.
А когда дело начинает касаться API-контроллеров, то вообще весело; прикрепить FosRestBundle не проблема (я говорю о более ленивом варианте, чем писать всё самому, хотя, как показывает практика, бандлом проще).
Итак, о чем я говорю? Прикрепили бандл, описали (в лучшем случае) входные параметры и правила с помощью ParameterFetcher. Вроде все готово и работает, запросы бегут, ответы летят. А вот что делать, когда нужна документация по API, я просто вариантов не увидел.
Самыми смертоносными были текстовые файлы в папке Resource/doc – но, по крайней мере, они служили там, где были нужны.
Я уверен, что для большинства из тех, кто прочитает эту статью и не закроет ее сразу, многое уже будет известно, но я все равно это опишу.
Все примеры я приведу со ссылками, где их взять и скриншотами того, как это работает. Итак, сам комплект - здесь .
Далее идет спойлер с установкой NelimoApiDocBundle. щелкнуть Устанавливается, как и все остальное, очень легко и просто через Composer:
Дальше еще проще в AppKernel.phprequire nelmio/api-doc-bundle
public function registerBundles()
{
//.
return array(
// .
new Nelmio\ApiDocBundle\NelmioApiDocBundle(),
);
}
Самое главное (ну хотя бы по отношению к статье) прописываем пути самого дженерика:
# app/config/routing.yml
NelmioApiDocBundle:
resource: "@NelmioApiDocBundle/Resources/config/routing.yml"
prefix: /api/doc
Далее я чисто поверхностно пройдусь по самым простым и основным моментам, предоставив вашему пытливому уму возможность прочитать и разобрать документацию, если возникнет такое желание.
Итак, у нас есть простой метод: щелкнуть public function getIndexAction(ParamFetcher $paramFetcher)
{
$view = View::create();
$result = [
'status' => 'success',
'data' => [
'someKey' => 'SomeValue'
]
];
$view->setData(['result' => $result]);
return $view;
}
Пока что этот метод ничем особенным не выделяется, и мы его немного расширим.
щелкнуть /**
* @Get(name="_additional_name_in_route", path="/")
*
* @Template(engine="twig", template="HabrApiDocBundle:Default:index.html.twig")
*
* @QueryParam(
* name="name",
* requirements="\w+",
* strict=true,
* nullable=false,
* description="Some description"
* )
*
* @param ParamFetcher $paramFetcher
* @return View
*/
public function getIndexAction(ParamFetcher $paramFetcher)
{
$view = View::create();
$result = [
'status' => 'success',
'data' => [
'someKey' => 'SomeValue'
]
];
$view->setData(['result' => $result]);
return $view;
}
Теперь вы можете разобраться, что мы там написали:
- @Get — это самый простой и быстрый способ переопределить URL-адрес маршрута для методов, которые отвечают только на один тип запроса (REST Full).
Это даст нам возможность сделать postIndexAction deleteIndexAction — и так далее, мы поняли.
- @Templating — использовать его или нет — решать вам.
Я предпочитаю использовать, например, для стандартизации ответов.
- @QueryParam — это первое преимущество: использование @QueryParam или @RequestParam соответственно позволит вам контролировать входные данные.
Например, у нас есть поле имени, которое не может быть пустым, должно соответствовать шаблону \w+, и не менее важным является поле «Описание», в котором вы можете написать, для чего его следует использовать.
* @ApiDoc(
* statusCodes={
* 200="Returned when successful",
* 403="Returned when the user is not authorized to say hello",
* 404={
* "Returned when the user is not found",
* "Returned when something else is not found"
* },
* },
* description = "Add here some description for this method",
* requirements = {
* {"name"="name", "datatype"="string", "requirements"="\w+", "description" = "description for this parameter"}
* },
* cache=false,
* tags = {
* "stable" = "green",
* "deprecated" = "#ff0000"
* },
* deprecated = true,
* section = "First section"
* )
Начну с описания по порядку:
- @ApiDoc() — естественно, вначале мы укажем сам бандл для использования,
- statusCodes — назначение этого параметра понятно из его названия, но в конечном итоге в документации он выглядит очень красиво, он расскажет нам, что и в каких случаях мы можем получить в качестве ответа.
- описание - ну тоже вроде капитан пришёл, с той лишь разницей, что теперь он будет виден в документации.
- требования — здесь прописывается массив параметров Запроса/Запроса с описанием их требований, которое также будет отображаться в документации.
- теги — теги — это просто нечто.
Когда к каждому методу можно поставить свой тег.
- deprecated — также хорошая функция, позволяющая отмечать методы, которые вы планируете больше не использовать.
- раздел — одно из самых полезных дополнений; он позволяет группировать методы, даже если они находятся в разных классах.
P.S> Поправил ссылку на скриншот Теги: #api #документация #аннотации #symfony 2 #nelmio-api-doc #php #symfony
-
5 Самых Частых Ошибок Менеджеров
19 Oct, 24 -
Язык D, Реализованный Gnu
19 Oct, 24 -
Не Используйте @Import
19 Oct, 24 -
Мтс Запустила Свою «Платежную Систему»
19 Oct, 24
