AgrSis Docs
API

Resumo da Instalação do Scribe - AgrSis API

Data: 2025-12-04 Versão Scribe: 5.6.0 Versão Laravel: 11

Resumo da Instalação do Scribe - AgrSis API

Data: 2025-12-04 Versão Scribe: 5.6.0 Versão Laravel: 11

Status da Instalação

✅ CONCLUÍDA COM SUCESSO

Todas as etapas foram executadas e a documentação está funcional.

O que foi Instalado e Configurado

1. Pacote Scribe

Instalação:

composer require --dev knuckleswtf/scribe

Versão instalada: 5.6.0

2. Configuração

Arquivo: /Users/gustavocarneiro/EMPRESA/web/agrsis/agrsis-v1/api/config/scribe.php

Principais configurações aplicadas:

  • Título: "AgrSis API"
  • Descrição: "API da plataforma AgrSis - Sistema de Licitação Eletrônica para Insumos Agrícolas"
  • Tipo: laravel (documentação integrada ao Laravel)
  • Base URL: Dinâmica via config('app.url')
  • Autenticação:
    • Habilitada: true
    • Padrão: true (todos endpoints autenticados por padrão)
    • Tipo: Bearer (Sanctum)
    • Header: Authorization
    • Placeholder: {SEU_TOKEN_SANCTUM}
  • Linguagens de exemplo: Bash, JavaScript, PHP, Python
  • Try It Out: Habilitado
  • Rotas: Prefixo api/*
  • Postman: Habilitado
  • OpenAPI: Habilitado (versão 3.0.3)

3. Rotas da API

Arquivo criado: /Users/gustavocarneiro/EMPRESA/web/agrsis/agrsis-v1/api/routes/api.php

Rotas implementadas:

Públicas (não autenticadas):

  • POST /api/v1/login - Login
  • POST /api/v1/register - Registro

Protegidas (autenticadas):

  • POST /api/v1/logout - Logout
  • GET /api/v1/me - Dados do usuário autenticado
  • GET /api/v1/produtos - Listar produtos
  • POST /api/v1/produtos - Criar produto
  • GET /api/v1/produtos/{id} - Exibir produto
  • PUT/PATCH /api/v1/produtos/{id} - Atualizar produto
  • DELETE /api/v1/produtos/{id} - Excluir produto

Total: 9 endpoints documentados

4. Controllers de Exemplo

Criados:

AuthController

Arquivo: /Users/gustavocarneiro/EMPRESA/web/agrsis/agrsis-v1/api/app/Http/Controllers/Api/AuthController.php

Endpoints:

  • login() - Login de usuários
  • register() - Registro de novos usuários
  • logout() - Logout
  • me() - Dados do usuário autenticado

Anotações incluídas:

  • @group Autenticação
  • @authenticated / @unauthenticated
  • @bodyParam para parâmetros do corpo
  • @response com exemplos de sucesso e erro

ProdutoController

Arquivo: /Users/gustavocarneiro/EMPRESA/web/agrsis/agrsis-v1/api/app/Http/Controllers/Api/ProdutoController.php

Endpoints:

  • index() - Listar produtos (com paginação)
  • store() - Criar produto
  • show() - Exibir produto
  • update() - Atualizar produto
  • destroy() - Excluir produto

Anotações incluídas:

  • @group Produtos
  • @authenticated
  • @urlParam para parâmetros de URL
  • @queryParam para query strings
  • @bodyParam para corpo da requisição
  • @response com múltiplos cenários (200, 201, 404, 422)

5. Bootstrap

Arquivo modificado: /Users/gustavocarneiro/EMPRESA/web/agrsis/agrsis-v1/api/bootstrap/app.php

Alteração:

->withRouting(
    web: __DIR__.'/../routes/web.php',
    api: __DIR__.'/../routes/api.php',  // ← ADICIONADO
    commands: __DIR__.'/../routes/console.php',
    health: '/up',
)

6. Documentação Gerada

Arquivos criados:

Views Blade:

  • resources/views/scribe/index.blade.php

Assets:

  • public/vendor/scribe/ (CSS, JS)

Arquivos intermediários:

  • .scribe/intro.md - Introdução customizada
  • .scribe/auth.md - Informações de autenticação
  • .scribe/endpoints/ - Endpoints processados
  • .scribe/endpoints.cache/ - Cache

Exportações:

  • storage/app/private/scribe/collection.json - Postman Collection
  • storage/app/private/scribe/openapi.yaml - OpenAPI Specification

7. README

Arquivo criado: /Users/gustavocarneiro/EMPRESA/web/agrsis/agrsis-v1/api/README_SCRIBE.md

Conteúdo:

  • Introdução ao Scribe
  • Como acessar a documentação
  • Como adicionar/atualizar documentação
  • Tipos de anotações disponíveis
  • Exemplos práticos completos
  • Comandos úteis
  • Exportação para Postman/Insomnia/Swagger
  • Configuração avançada
  • Boas práticas
  • Troubleshooting

Arquivos Criados/Modificados

Criados:

  1. /api/config/scribe.php - Configuração do Scribe
  2. /api/routes/api.php - Rotas da API
  3. /api/app/Http/Controllers/Api/AuthController.php - Controller de autenticação
  4. /api/app/Http/Controllers/Api/ProdutoController.php - Controller de produtos
  5. /api/README_SCRIBE.md - Documentação completa de uso
  6. /api/.scribe/ - Diretório com arquivos gerados
  7. /api/resources/views/scribe/ - Views da documentação
  8. /api/public/vendor/scribe/ - Assets (CSS/JS)
  9. /api/storage/app/private/scribe/collection.json - Postman Collection
  10. /api/storage/app/private/scribe/openapi.yaml - OpenAPI Spec
  11. /api/INSTALACAO_SCRIBE_RESUMO.md - Este arquivo

Modificados:

  1. /api/bootstrap/app.php - Adicionada rota API
  2. /api/composer.json - Adicionado Scribe nas dependências dev
  3. /api/composer.lock - Atualizado com novas dependências

Como Acessar a Documentação

Localmente (sem Docker - servidor não está rodando)

# Navegar até o diretório
cd /Users/gustavocarneiro/EMPRESA/web/agrsis/agrsis-v1/api

# Iniciar servidor
php artisan serve

# Acessar no navegador:
# http://localhost:8000/docs

Com Docker (container não está rodando)

# Navegar até o diretório raiz do projeto
cd /Users/gustavocarneiro/EMPRESA/web/agrsis/agrsis-v1

# Iniciar containers
docker-compose up -d

# Acessar no navegador:
# http://localhost:8000/docs

URLs Disponíveis:

Próximos Passos Recomendados

1. Testar a Documentação

# Iniciar servidor
cd /Users/gustavocarneiro/EMPRESA/web/agrsis/agrsis-v1/api
php artisan serve

# Abrir navegador em http://localhost:8000/docs

2. Adicionar Mais Endpoints

À medida que você criar novos controllers:

  1. Adicione as anotações do Scribe
  2. Execute php artisan scribe:generate
  3. Verifique a documentação em /docs

3. Importar no Postman

# Copiar collection para área de trabalho
cp storage/app/private/scribe/collection.json ~/Desktop/agrsis-api-postman.json

Depois importe no Postman: Import → File → Selecione o arquivo

4. Configurar CORS (se necessário)

Se for usar "Try It Out" de outro domínio, configure CORS:

# Instalar Laravel CORS (já deve estar instalado)
composer require fruitcake/laravel-cors

# Configurar em config/cors.php

5. Adicionar Logo (opcional)

  1. Coloque a logo em public/img/logo.png
  2. Edite config/scribe.php: 
    'logo' => 'img/logo.png',
  3. Regere: php artisan scribe:generate

6. Documentar Endpoints Reais

Os controllers criados são apenas exemplos. Quando implementar os endpoints reais:

  1. Mantenha as anotações do Scribe
  2. Ajuste os exemplos de resposta com dados reais
  3. Adicione todos os cenários de erro possíveis
  4. Documente validações específicas

7. Criar Model User (se não existir)

O AuthController usa App\Models\User. Se não existir, crie:

php artisan make:model User

E configure conforme necessário com Sanctum.

Comandos Úteis

# Gerar documentação
php artisan scribe:generate

# Limpar cache e gerar
php artisan route:clear && php artisan config:clear && php artisan scribe:generate

# Limpar cache de endpoints
rm -rf .scribe/endpoints.cache/*

# Ver rotas registradas
php artisan route:list --path=api

# Exportar collection Postman
cp storage/app/private/scribe/collection.json ~/Desktop/

# Exportar OpenAPI spec
cp storage/app/private/scribe/openapi.yaml ~/Desktop/

Estrutura Final de Diretórios

/Users/gustavocarneiro/EMPRESA/web/agrsis/agrsis-v1/api/
│
├── app/
│   └── Http/
│       └── Controllers/
│           └── Api/
│               ├── AuthController.php       ← NOVO
│               └── ProdutoController.php    ← NOVO
│
├── config/
│   └── scribe.php                           ← NOVO
│
├── routes/
│   ├── api.php                              ← NOVO
│   ├── console.php
│   └── web.php
│
├── resources/views/scribe/                  ← NOVO (gerado)
│   └── index.blade.php
│
├── public/vendor/scribe/                    ← NOVO (gerado)
│   ├── css/
│   └── js/
│
├── storage/app/private/scribe/              ← NOVO (gerado)
│   ├── collection.json
│   └── openapi.yaml
│
├── .scribe/                                 ← NOVO (gerado)
│   ├── auth.md
│   ├── intro.md
│   ├── endpoints/
│   └── endpoints.cache/
│
├── bootstrap/
│   └── app.php                              ← MODIFICADO
│
├── README_SCRIBE.md                         ← NOVO
├── INSTALACAO_SCRIBE_RESUMO.md             ← NOVO (este arquivo)
├── composer.json                            ← MODIFICADO
└── composer.lock                            ← MODIFICADO

Grupos Documentados

  1. Autenticação
    • Login
    • Registro
    • Logout
    • Dados do Usuário Autenticado
  2. Produtos
    • Listar (com paginação, busca, filtros)
    • Criar
    • Exibir
    • Atualizar
    • Excluir

Informações Técnicas

Dependências Instaladas:

  • knuckleswtf/scribe: ^5.6
  • erusev/parsedown: 1.7.4
  • mpociot/reflection-docblock: 1.0.1
  • shalvah/clara: 3.3.0
  • shalvah/upgrader: 0.6.0
  • symfony/var-exporter: v7.4.0

Configurações do Laravel Modificadas:

  • Rotas API habilitadas no bootstrap
  • Prefixo padrão: /api
  • Middleware: api

Notas Importantes

  1. Container Docker: O container agrsis_api não está rodando no momento. Para usar com Docker, inicie os containers primeiro.
  2. Model User: Os controllers usam App\Models\User. Certifique-se de que existe e está configurado com Sanctum.
  3. Banco de Dados: As implementações dos controllers são apenas exemplos. Conecte-os ao banco de dados real quando implementar.
  4. CORS: Configure CORS se for usar "Try It Out" de outro domínio.
  5. Autenticação: A configuração está preparada para Laravel Sanctum. Configure o Sanctum se ainda não estiver configurado.
  6. Produção: Quando for para produção:
    • Gere a documentação: php artisan scribe:generate
    • Configure a URL base correta em .env
    • Considere adicionar autenticação para acessar /docs se necessário

Referências

Suporte

Para dúvidas sobre:

  • Como usar: Consulte /api/README_SCRIBE.md
  • Configuração: Veja config/scribe.php (bem comentado)
  • Exemplos: Veja os controllers em app/Http/Controllers/Api/
  • Documentação oficial: https://scribe.knuckles.wtf/laravel

Instalação concluída com sucesso!

Todos os arquivos foram criados e a documentação está pronta para uso. Basta iniciar o servidor e acessar /docs.

Testes de Factories - AgrSis

Documentação da API com Scribe

Este documento explica como usar e manter a documentação da API do AgrSis usando o Scribe.

Copyright © 2026