Documente Seus Endpoints Laravel com Swagger de Forma Automática

Como desenvolvedores, todos sabemos o quanto é importante ter uma boa documentação de API. Mas manter essa documentação atualizada pode se tornar uma tarefa cansativa — especialmente durante fases de desenvolvimento rápido.

Foi por isso que criei a Laravel Perry: uma biblioteca que ajuda você a gerar documentação Swagger automaticamente a partir dos seus testes end-to-end (E2E).

Se você já escreve testes E2E para sua API em Laravel, o Perry cuida da documentação pra você, sem precisar escrever manualmente os arquivos do OpenAPI.

Como Funciona

Durante a execução dos testes, o Perry captura as requisições feitas aos seus endpoints, incluindo headers, request, response etc. Ele então gera automaticamente um arquivo .yaml compatível com Swagger para cada rota.

Veja um exemplo de teste:

function test_shouldCreateUser() {
    $this
        ->perryHttp()
        ->withHeaders(['api_key' => 'some_api_key'])
        ->withBody([
            'name' => 'John Doe',
            'age' => 25,
            'email' => 'john@doe.com',
            'password' => 'password',
        ])
        ->post('/user')
        ->assertJson(['success' => true])
        ->assertStatus(Response::HTTP_CREATED);
}

Ao rodar esse teste, o Perry irá capturar a requisição e a resposta e gerar automaticamente a documentação Swagger desse endpoint

Ou seja: sua documentação evolui junto com seus testes, garantindo que esteja sempre atualizada.

Instalação

Instale a biblioteca com o Composer:

composer require n4m-ward/laravel-perry

Depois execute seus testes E2E e crie a documentação com o comando a baixo:

./vendor/bin/perry

Por Que Usar o Perry?

  • Sem trabalho manual: sua suíte de testes vira a fonte da documentação
  • Sempre atualizada: se o teste muda, a documentação muda
  • Documentação orientada a testes: estimula testes melhores
  • Configuração rápida: integre em poucos minutos no seu projeto Laravel

Roadmap & Contribuições

Essa biblioteca ainda está em evolução. Aqui estão algumas melhorias planejadas:

  • Agrupamento de endpoints com tags
  • Inferência de tipos aprimorada
  • Suporte a detalhes de middleware e autenticação

Sugestões São Bem-Vindas

Sugestões e feedbacks são muito bem-vindos! Sinta-se à vontade para abrir uma pull request ou criar uma issue no GitHub se tiver ideias, sugestões ou encontrar algum problema.

Confira o projeto no GitHub: https://github.com/n4m-ward/perry