O que é o NelmioApiDocBundle?
O NelmioApiDocBundle é um pacote do Symfony que fornece muito mais documentação detalhada de sua API REST em comparação a outras bibliotecas (Swagger, Apiary, apidoc.js, etc.).
O bundle é capaz de analisar o código fonte de suas rotas e usar a sintaxe de anotação específica para gerar uma documentação útil que pode ser facilmente personalizada. É fácil de integrar, personalizar e é altamente expansível.
Usando o NelmioApiDocBundle você pode obter documentação clara do seu código e manter a sua base de código de API limpa e fácil de ler, poupando muito tempo e esforço no desenvolvimento da documentação. Além disso, os desenvolvedores de todo o mundo vão conseguir entender e usar a API rapidamente por causa dessa documentação detalhada e precisa.
Como instalar o NelmioApiDocBundle?
Primeiro, você precisa do Symfony instalado e funcionando. Depois, abra o terminal e execute o seguinte comando:
composer require nelmio/api-doc-bundleUma vez que o pacote foi instalado, registre-o no AppKernel.php. Adicione a linha seguinte ao array $bundle pré-existente de bundles:
new NelmioApiDocBundleNelmioApiDocBundle(),Por fim, configure as rotas ou quaisquer outras opções específicas de personalização em app/config/config.yml do seu projeto.
Como documentar minha API com o NelmioApiDocBundle?
O NelmioApiDocBundle é bem fácil de usar. Depois de instalar o pacote e registrar o bundle, comente todas as suas rotas na sua aplicação com anotações que conhecem todas as partes expostas da sua API.
Existem diferentes anotações para diferentes partes de sua API. Por exemplo, sinônimos de rota, descrição de parâmetros e respostas, sinônimos de anotações, nome de arquivo e etc.
Depois de comentar suas rotas, rode o comando php app/console nelmio:api:doc:generate no seu terminal. Isso irá gerar um arquivo HTML com a documentação da sua API. Personalize do jeito que quiser e está tudo pronto!
Posso personalizar a aparência do NelmioApiDocBundle?
Claro! É possível mudar a aparência do NelmioApiDocBundle ao implementar os seguintes arquivos de modelo:
- overview.html.twig – A página principal da documentação
- collections.html.twig – Lista todas as coleções de rota
- collection.html.twig – Lista uma coleção de rota única
- method.html.twig – Mostra detalhes de uma rota
Além disso, é possível criar seu próprio tema adicionando os arquivos de modelo ao seu projeto e definindo sua localização com o parâmetro template_dir em app/config/config.yml da seguinte maneira:
nelmio_api_doc: template_dir: '@AppBundle/docs'Posso ver a documentação da API no navegador?
Sim é possível. Para ver a documentação da API no seu navegador, inicie o servidor web interno do Symfony com o seguinte comando:
php bin/console server:startAcessando http://localhost:8000/api/doc no seu navegador, a documentação que você gerou com a biblioteca NelmioApiDocBundle deve carregar.
Como faço para adicionar testes à minha API usando o NelmioApiDocBundle?
O NelmioApiDocBundle fornece um cliente (@NelmioAlicesupportSymfony) de teste para suas rotas. Ele permite enviar solicitações a sua API e verificar as respostas recebidas.
Para usá-lo, basta criar um novo EntityBuilder usando a biblioteca NelmioAliceDataFixture e adicionar suas rotas à análise. Depois disso, você pode criar objetos para verificar as solicitações enviadas e as respostas recebidas.
Os objetos Criados com a Biblioteca NelmioAliceDataFixture são independentes dos tipos de Entity e de Qualquer outro servidor utilizado em qualquer teste na aplicação. Isso torna seus testes altamente flexíveis, reutilizáveis. Para ajudar na aprendizagem, aqui está uma visão geral de como os testes são implementados usando o NelmioApiDocBundle:
use DoctrineORMEntityManager;
use DoctrineCommonDataFixturesAbstractFixture;
use SymfonyComponentHttpFoundationRequest;
use nelmioapi-doc-bundleTestsFixturesTestClient as Client;
class RequestTest extends AbstractFixture
{
private $em, $client;
public function load(EntityManager $em)
{
$this->em = $em;
$this->client = new Client($this->em);
}
public function testRequests()
{
$response = $this->client->request(Request::METHOD_GET, '/api/doc');
$this->assertEquals($response->getStatusCode(), 200);
}
}
Posso usar o NelmioApiDocBundle com outras bibliotecas do Symfony?
Claro! O NelmioApiDocBundle pode ser facilmente integrado com outras bibliotecas Symfony.
Por exemplo, você pode integrá-lo com o FOSRestBundle para criar APIs REST no Symfony e o Swagger-ui-bundle para visualizar e experimentar APIs REST. Se você quiser usar o JMS Serializer Bundle para serializar suas respostas de API, o NelmioApiDocBundle também oferece fácil integração.
Basta instalar esses pacotes, registrar em AppKernel.php, configurá-los em app/config/config.yml e adicionar as anotações corretas às suas rotas de API. Tudo isso será feito rapidamente e com facilidade com algumas alterações simples no seu código.
O NelmioApiDocBundle é atualizado regularmente?
“Sim, o NelmioApiDocBundle é atualizado regularmente. Os desenvolvedores que trabalham nesta biblioteca estão muito comprometidos em corrigir bugs, implementar novas funcionalidades e manter esta biblioteca atualizada com as novas atualizações do Symfony.”
Posso personalizar a sintaxe de anotação do NelmioApiDocBundle?
Sim, é possível personalizar a sintaxe de anotação do NelmioApiDocBundle.
Você só precisa definir sua própria classe de anotação (@Annotation) e usar na documentação da sua API. Na verdade, o NelmioApiDocBundle usa o DoctrineAnnotationReader, um leitor de anotações compatível com o Doctrine, para gerenciar suas anotações. Isso torna muito fácil personalizar e usar anotações personalizadas no seu projeto.
Então, se você precisar de um novo tipo de anotação para um novo recurso de API, crie uma classe de anotação personalizada, use a sintaxe da sua nova anotação e então execute php app/console nelmio:api:doc:generate. Tudo estará documentado!
Posso usar o NelmioApiDocBundle em aplicativos Symfony antigos?
Claro! O NelmioApiDocBundle pode ser usado em grandes projetos do Symfony, mesmo os mais antigos que usaram uma versão anterior do Symfony.
Basta seguir as instruções de instalação simples mencionadas acima e começar a documentar as rotas que já existem.
Uma vez que sua API está documentada, você pode aproveitar a documentação de API clara e completa e mantê-la atualizada facilmente. Não há necessidade de volta e construir novamente seu projeto a partir do zero com esta biblioteca Symfony fantástica.