AgrSis Docs
API

Scribe - Referência Rápida (Quick Reference)

Guia rápido para uso diário do Scribe na API AgrSis.

Scribe - Referência Rápida (Quick Reference)

Guia rápido para uso diário do Scribe na API AgrSis.

🚀 Comandos Principais

# Gerar/Atualizar documentação
php artisan scribe:generate

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

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

📍 URLs de Acesso

Documentação HTML:  http://localhost:8000/docs
Postman Collection: http://localhost:8000/docs.postman
OpenAPI Spec:       http://localhost:8000/docs.openapi

📝 Anotações Mais Usadas

Grupo (na classe)

/**
 * @group Nome do Grupo
 *
 * Descrição do grupo
 */
class SeuController extends Controller

Endpoint Básico

/**
 * Título do Endpoint
 *
 * Descrição detalhada.
 *
 * @authenticated
 *
 * @response 200 {
 *   "success": true,
 *   "data": {...}
 * }
 */
public function metodo()

Parâmetros

// URL
@urlParam id integer required ID do recurso. Example: 1

// Query String
@queryParam page integer Número da página. Example: 1

// Body
@bodyParam nome string required Nome. Example: João Silva

Tipos de Dados

string | integer | int | number | float | boolean | bool | array | object | file

Múltiplas Respostas

/**
 * @response 200 {
 *   "success": true
 * }
 *
 * @response 404 {
 *   "message": "Not Found"
 * }
 */

📋 Checklist para Novo Endpoint

  • Criar rota em routes/api.php
  • Criar método no controller
  • Adicionar @group (se novo grupo)
  • Adicionar @authenticated ou @unauthenticated
  • Adicionar @urlParam se houver
  • Adicionar @queryParam se houver
  • Adicionar @bodyParam se houver
  • Adicionar @response com exemplos
  • Executar php artisan scribe:generate
  • Testar em http://localhost:8000/docs

🎯 Exemplos Rápidos

GET com Query Params

/**
 * Listar Recursos
 *
 * @authenticated
 *
 * @queryParam page integer Página. Example: 1
 * @queryParam search string Busca. Example: termo
 *
 * @response 200 {
 *   "data": [],
 *   "total": 50
 * }
 */
public function index(Request $request)

POST

/**
 * Criar Recurso
 *
 * @authenticated
 *
 * @bodyParam nome string required Nome. Example: Produto A
 * @bodyParam preco number required Preço. Example: 100.50
 *
 * @response 201 {
 *   "success": true,
 *   "data": {...}
 * }
 *
 * @response 422 {
 *   "errors": {...}
 * }
 */
public function store(Request $request)

PUT/PATCH

/**
 * Atualizar Recurso
 *
 * @authenticated
 *
 * @urlParam id integer required ID. Example: 1
 * @bodyParam nome string Nome. Example: Novo Nome
 *
 * @response 200 {
 *   "success": true
 * }
 *
 * @response 404 {
 *   "message": "Not Found"
 * }
 */
public function update(Request $request, $id)

DELETE

/**
 * Excluir Recurso
 *
 * @authenticated
 *
 * @urlParam id integer required ID. Example: 1
 *
 * @response 200 {
 *   "success": true
 * }
 *
 * @response 404 {
 *   "message": "Not Found"
 * }
 */
public function destroy($id)

Upload de Arquivo

/**
 * Upload de Arquivo
 *
 * @authenticated
 *
 * @bodyParam arquivo file required Arquivo. Example: /path/to/file.pdf
 *
 * @response 200 {
 *   "url": "https://..."
 * }
 */
public function upload(Request $request)

🔧 Troubleshooting Rápido

Endpoint não aparece

# Limpar caches
php artisan route:clear
php artisan config:clear
rm -rf .scribe/endpoints.cache/*
php artisan scribe:generate

Try It Out não funciona

// config/scribe.php
'try_it_out' => [
    'enabled' => true,
    'base_url' => null, // ou URL específica
],

Autenticação não aparece nos exemplos

// config/scribe.php
'auth' => [
    'enabled' => true,
    'default' => true,
],

// E no método:
/**
 * @authenticated
 */

📂 Arquivos Importantes

config/scribe.php              # Configuração principal
routes/api.php                 # Rotas da API
.scribe/                       # Cache (pode deletar)
storage/app/private/scribe/    # Exportações
README_SCRIBE.md              # Documentação completa

🎨 Customizações Comuns

Mudar URL Base

// config/scribe.php
'base_url' => 'https://api.agrsis.com.br',

// config/scribe.php
'logo' => 'img/logo.png',

Mudar Linguagens de Exemplo

// config/scribe.php
'example_languages' => [
    'bash',
    'javascript',
    'php',
    'python', // ou remova se não quiser
],

Excluir Rotas

// config/scribe.php
'routes' => [
    [
        'exclude' => [
            'GET /health',
            'admin.*',
        ],
    ],
],

💡 Dicas Úteis

  1. Sempre use exemplos realistas
    // ❌ Ruim
@bodyParam nome string Example: string

// ✅ Bom
@bodyParam nome string Example: Fertilizante NPK 10-10-10
  2. Documente todos os cenários de erro
    @response 200 {...}    // Sucesso
@response 401 {...}    // Não autenticado
@response 404 {...}    // Não encontrado
@response 422 {...}    // Validação
  3. Use descrições claras
    // ❌ Ruim
/**
 * Index
 */

// ✅ Bom
/**
 * Listar Produtos
 *
 * Retorna uma lista paginada de produtos ativos,
 * com suporte a busca e filtros.
 */
  4. Mantenha sincronizado
    • Sempre gere após alterações
    • Revise periodicamente
    • Teste os exemplos

🔗 Links Úteis

Imprima este documento e mantenha próximo durante o desenvolvimento!

Estatísticas da Documentação Scribe - AgrSis API

Gerado em: 2025-12-04 Versão Scribe: 5.6.0

Frontend

Guias e padrões dos portais Producer, Supplier e Admin.

Copyright © 2026