A documentação eficaz de APIs é fundamental para o desenvolvimento de aplicações robustas e de fácil manutenção. No ecossistema Laravel, o Scramble se destaca como uma ferramenta inovadora que automatiza a geração de documentação de APIs, eliminando a necessidade de anotações manuais em PHPDoc.
O que é o Scramble?
O Scramble é um pacote para Laravel que utiliza análise estática de código para gerar automaticamente a documentação da sua API. Ao seguir as convenções do Laravel, ele identifica rotas, parâmetros e respostas, criando uma documentação sempre atualizada e sincronizada com o código.
Principais Recursos
• Geração Automática de Documentação: Dispensa a escrita manual de anotações, reduzindo erros e garantindo que a documentação reflita o estado atual do código.
• Interface Interativa: Oferece uma interface de usuário baseada em componentes React ou Web Components, permitindo a interação direta com os endpoints documentados.
• Conformidade com OpenAPI: Gera documentos no formato OpenAPI, facilitando a integração com outras ferramentas e serviços.
• Análise de Validações: Detecta automaticamente parâmetros obrigatórios a partir de validações definidas no código, como em Form Requests ou chamadas ao método validate().
Vantagens de Utilizar o Scramble
• Economia de Tempo: Automatiza a criação da documentação, permitindo que os desenvolvedores foquem no desenvolvimento das funcionalidades principais.
• Manutenção Simplificada: A documentação se atualiza conforme o código evolui, evitando desatualizações comuns em métodos manuais.
• Segurança e Confiabilidade: Ao refletir fielmente o comportamento da API, a documentação gera maior confiança para desenvolvedores e usuários finais.
Como Integrar o Scramble no Seu Projeto Laravel
1. Instalação: Adicione o pacote ao seu projeto via Composer:
O Scramble requer:
- PHP 8.1 ou superior
- Laravel 10.x ou superior
Você pode instalar o Scramble via composer:Terminal window
composer require dedoc/scrambleQuando o Scramble é instalado, 2 rotas são adicionadas ao seu aplicativo:
- /docs/api – Visualizador de IU para sua documentação
- /docs/api.json – Abre o documento da API no formato JSON descrevendo sua API.
E é isso! Agora você pode visitar /docs/api para ver a documentação da sua API.
Por padrão, essas rotas estão disponíveis apenas no ambiente local. Você pode alterar esse comportamento definindo viewApiDocs gate.
Publicação de configuração
Opcionalmente, você pode publicar o arquivo de configuração do pacote: janela Terminal
php artisan vendor:publish --provider="Dedoc\Scramble\ScrambleServiceProvider" --tag="scramble-config"Isso permitirá que você personalize a resolução de rotas de API e os detalhes do documento OpenAPI.
O conteúdo da configuração scramble:
<?php
use Dedoc\Scramble\Http\Middleware\RestrictedDocsAccess;
return [
/*
* Your API path. By default, all routes starting with this path will be added to the docs.
* If you need to change this behavior, you can add your custom routes resolver using `Scramble::routes()`.
*/
'api_path' => 'api',
/*
* Your API domain. By default, app domain is used. This is also a part of the default API routes
* matcher, so when implementing your own, make sure you use this config if needed.
*/
'api_domain' => null,
'info' => [
/*
* API version.
*/
'version' => env('API_VERSION', '0.0.1'),
/*
* Description rendered on the home page of the API documentation (`/docs/api`).
*/
'description' => '',
],
/*
* The list of servers of the API. By default (when `null`), server URL will be created from
* `scramble.api_path` and `scramble.api_domain` config variables. When providing an array, you
* will need to specify the local server URL manually (if needed).
*
* Example of non-default config (final URLs are generated using Laravel `url` helper):
*
* ```php
* 'servers' => [
* 'Live' => 'api',
* 'Prod' => 'https://scramble.dedoc.co/api',
* ],
* ```
*/
'servers' => null,
'middleware' => [
'web',
RestrictedDocsAccess::class,
],
'extensions' => [],
];Agora, depois de instalar o Scramble, a primeira coisa a fazer é garantir que todas as rotas da API sejam adicionadas aos documentos.
Resolução de rotas
Por padrão, todas as rotas que começam com api são adicionadas à documentação. Por exemplo, yoursite.com/api/users será adicionado aos documentos. Isso pode ser personalizado modificando o valor de configuração scramble.api_path. Por exemplo, se você quiser adicionar todas as rotas que começam com api/v1, você deve definir scramble.api_path como api/v1. Certifique-se de publicar o arquivo de configuração primeiro.
Se suas rotas de API usarem um domínio diferente, você pode contabilizá-lo modificando o valor de configuração scramble.api_domain. Por padrão, ele é definido como null, o que significa que o domínio atual será usado. Então, se suas rotas de API estiverem em api.yoursite.com, você deve definir scramble.api_domain como api.yoursite.com.
Além disso, você pode fornecer sua própria função de resolução de rotas usando Scramble::route no método boot de um provedor de serviços. Dessa forma, você pode excluir rotas ou incluir apenas algumas. Ela terá precedência sobre a correspondência de rota padrão. Por exemplo, em seu AppServiceProvider:
use Illuminate\Support\Str;
use Dedoc\Scramble\Scramble;
use Illuminate\Routing\Route;
public function boot(): void
{
Scramble::routes(function (Route $route) {
return Str::startsWith($route->uri, 'api/');
});
}A função de resolução de rota aceita uma rota e retorna um bool determinando se a rota deve ser adicionada aos documentos ou não.
Neste ponto, seus documentos devem estar disponíveis em /docs/api URI.
O Scramble representa um avanço significativo na documentação de APIs em Laravel, oferecendo uma solução automatizada, precisa e de fácil integração. Ao adotá-lo, equipes de desenvolvimento podem assegurar que suas APIs estejam sempre bem documentadas, facilitando a colaboração e a manutenção dos projetos.
Para mais detalhes e acesso a documentação: https://scramble.dedoc.co/usage/getting-started
