single_software/singles_swagger

create dinamic api-docs

2.0.4 2024-06-06 15:07 UTC

Requires

• php: *
• illuminate/container: *
• illuminate/events: *
• illuminate/routing: *
• laravel/framework: *
• spatie/laravel-settings: *

Requires (Dev)

• laravel/sail: ^1.29
• laravel/tinker: ^2.9
• nunomaduro/collision: ^8.1
• phpunit/phpunit: ^11.1

MIT

• Beto006

README

Uma biblioteca para gerar documentação Swagger automaticamente para APIs Laravel, com base em FormRequests.

Instalação

Instale a biblioteca usando o Composer:

composer require single_software/singles_swagger

Funcionalidades

Rotas de Documentação

Após instalar a biblioteca, você poderá acessar a documentação Swagger gerada automaticamente através das seguintes rotas:

• /api-doc/{routeName}
  Exemplo: /api-doc/api.php

  Gera a documentação Swagger para um arquivo de rotas específico.

• /api-doc
  Lista todas as rotas disponíveis para documentação.
  Exemplo de saída:

  [
      "api.php",
      "web.php",
      "api.json"
  ]

• /api-doc/api.json
  Disponibiliza a documentação Swagger no formato JSON para integração com ferramentas externas.

Comando Artisan

A biblioteca fornece um comando Artisan para gerar a documentação Swagger manualmente:

php artisan generate:swagger {routeFile} {--prefix=} {--tenants=}

Parâmetros do Comando:

• {routeFile}
  O nome do arquivo de rotas para o qual a documentação será gerada.
  Exemplo: api.php

• {--prefix=}
  Um prefixo para as rotas que deve ser considerado na documentação.
  Exemplo: --prefix=api/v1

• {--tenants=}
  Indica que as rotas pertencem a um sistema com múltiplos tenants (multitenancy).
  Exemplo: --tenants=true

Exemplos de Uso

1. Gerar Documentação para um Arquivo de Rotas Específico

Acesse a rota:

http://sua-aplicacao.test/api-doc/api.php

Ou execute o comando Artisan:

php artisan generate:swagger api.php

2. Listar Todas as Rotas Disponíveis

Acesse:

http://sua-aplicacao.test/api-doc

3. Exportar Documentação como JSON

Acesse:

http://sua-aplicacao.test/api-doc/api.json

Benefícios

• Automação Completa: Geração automática de documentação com base em validações definidas em FormRequest.
• Flexibilidade: Suporte a sistemas com múltiplos tenants e rotas com prefixos personalizados.
• Integração Simples: Use o formato JSON para integrar a documentação com ferramentas externas, como Swagger UI.

Requisitos

• Laravel 8 ou superior.
• PHP 7.4 ou superior.

Sobre

Esta biblioteca foi desenvolvida pela SingleSoftware para facilitar a criação de documentações Swagger em projetos Laravel.