API

/laravel-agent:api:docs

Generate OpenAPI/Swagger API documentation

Overview

The /api:docs command generates comprehensive API documentation using Laravel's popular documentation packages. It supports multiple output formats including interactive HTML documentation, OpenAPI specifications, and Postman collections.

Usage

/laravel-agent:api:docs [format]

Examples

# Generate with Scribe (default)
/laravel-agent:api:docs

# Generate OpenAPI 3.0 specification
/laravel-agent:api:docs openapi

# Generate Postman collection
/laravel-agent:api:docs postman

Documentation Packages

The command automatically detects and uses one of two popular Laravel API documentation packages:

Scribe (Recommended)

Full-featured, attribute-based documentation with extensive customization options. Scribe reads your code annotations and generates beautiful, interactive documentation.

<?php

namespace App\Http\Controllers\Api\V1;

/**
 * @group Orders
 * @authenticated
 */
class OrderController
{
    /**
     * List orders
     *
     * @queryParam status Filter by status. Example: pending
     * @response 200 scenario="success" {"data": [...]}
     */
    public function index() {}
}

Scramble

Zero-config documentation that auto-generates from your code structure. Scramble analyzes your routes, controllers, and models to create documentation without requiring manual annotations.

Process

The command follows these steps to generate documentation:

  1. Check Documentation Package - Detects which documentation package is installed (Scribe or Scramble)
  2. Generate Documentation - Runs the appropriate generation command for the detected package
  3. Report Results - Provides a summary of documented endpoints and any missing documentation

Output Formats

Generated documentation is available in multiple formats:

Format Location Description
HTML /docs Interactive web documentation with try-it-out functionality
OpenAPI /docs/openapi.yaml OpenAPI 3.0 specification for client generation
Postman /docs/collection.json Postman collection for API testing

Detection Commands

The agent uses these commands to detect installed documentation packages:

# Check for Scribe
composer show knuckleswtf/scribe 2>/dev/null && echo "SCRIBE=yes" || echo "SCRIBE=no"

# Check for Scramble
composer show dedoc/scramble 2>/dev/null && echo "SCRAMBLE=yes" || echo "SCRAMBLE=no"

Generation Commands

Based on the detected package, the appropriate command is executed:

# Scribe - Generate comprehensive documentation
php artisan scribe:generate

# Scramble - Auto-generates from code
# Documentation available at /docs/api

Example Report

After generation, you'll receive a detailed report like this:

## API Documentation Generated

### Access
- HTML: /docs
- OpenAPI: /docs/openapi.yaml
- Postman: /docs/collection.json

### Endpoints Documented
- Auth: 4 endpoints
- Users: 5 endpoints
- Orders: 6 endpoints

### Missing Documentation
- POST /api/v1/webhooks (no description)
- GET /api/v1/reports (missing response example)

Best Practices

  1. Document as you code - Add annotations while creating endpoints, not after
  2. Provide examples - Include realistic request and response examples
  3. Group endpoints - Use @group tags to organize related endpoints
  4. Update regularly - Regenerate docs after API changes
  5. Review output - Check the generated docs for completeness and accuracy

See Also