DOCSEARCHbyAlgolia
Submit Docs

Scramble OpenAPI Documentation for Laravel

website·Indexed 34 days ago

https://scramble.dedoc.co/

Scramble automatically generates OpenAPI documentation for Laravel endpoints by analyzing the codebase. It provides type inference for requests and responses, support for Spatie Laravel Data and Laravel Query Builder, and integrates with UI renderers like Stoplight Elements and Scalar. The tool supports multiple API versions, JSON:API, and automatic documentation of API authentication.

Tokens
34.3K
Snippets
190
Records
252
Agent score
66%

What's inside Scramble

  1. Overview of Scramble API documentation generation

    Scramble is a Laravel package that generates API documentation using static code analysis and Laravel conventions. Unlike traditional tools, it does not require PHPDoc annotations for basic documentation, though they can be used for fine-grained control over parameter descriptions and response types.

    After installation, Scramble provides two primary endpoints:

    1. /docs/api: The user interface for viewing documentation.
    2. /docs/api.json: The endpoint that generates the underlying OpenAPI document.

  2. Overview of Scramble Laravel OpenAPI Generator

    Scramble is an automatic OpenAPI (Swagger) documentation generator for Laravel projects. Unlike traditional tools, it generates API documentation directly from your code without requiring manual PHPDoc annotations, ensuring that the documentation remains up-to-date as the code evolves. The generated documentation follows the OpenAPI 3.1.0 specification and is rendered using Stoplight Elements for the UI.

  3. Automatically document Laravel JSON Resources

    Scramble automatically generates OpenAPI response documentation by analyzing the toArray return type of Laravel JSON resources. Resources are stored as reusable schema components in the OpenAPI document, using the resource class's basename as the schema name by default.
    use Illuminate	tp
esourcesromJson
esource;

class PostResource extends JsonResource
{
    public function toArray(): array
    {
        return [
            'id' => $this->id,
            'title' => $this->title,
            'body' => $this->body,
            'author' => UserResource::make($this->whenLoaded('author')),
        ];
    }
}

  4. Document JSON:API Resources with Scramble

    Scramble automatically documents resources that extend JsonApiResource, including their attributes, relationships, and JSON:API-compliant query parameters (include and fields[*]). Attributes are marked as optional in the documentation because they can be excluded via sparse fieldsets.

  6. Customize the API documentation overview page

    You can add a description to the API overview page by setting the scramble.info.description configuration value. Markdown is supported.
    return [
    'info' => [
        'description' => 'This is my **API** description',
    ],
];

  7. Generate API documentation for Spatie Laravel Data

    Scramble PRO provides automated API documentation generation for projects using the Spatie Laravel Data package. It allows developers to maintain strongly-typed API objects that are automatically reflected in the documentation without manual OpenAPI file updates.
    use App//Data
use App//Data
use App//Http//Controllers//Controller
use App//Models//Company
use App//Models//Job

class CompaniesJobsController extends Controller
{
    public function store(Company $company, JobPayloadData $jobPayload)
    {
        $job = Job::make($jobPayload);
        $company->jobs()->save($job);
        return JobData::from($job);
    }
}

  8. Document Laravel Resource Collections

    Scramble supports the documentation of Laravel resource collections, allowing it to correctly identify and document endpoints that return a collection of resources, including how those resources are wrapped in the response and any additional data included in the collection.

  9. Generate API documentation for Spatie Laravel Query Builder

    Scramble PRO automates the generation of API documentation for endpoints utilizing Spatie's Laravel Query Builder. It can document allowed fields, filters, includes, and sorts defined in the QueryBuilder instance.
    use App//Data//CompanyData
use App//Http//Controllers//Controller
use App//Models//Company
use Illuminate//Http//Request
use Spatie//LaravelData//PaginatedDataCollection
use Spatie//QueryBuilder//QueryBuilder

class CompaniesController extends Controller
{
    public function index(Request $request)
    {
        $companies = QueryBuilder::for(Company::class)
            ->allowedFields(['id', 'name', 'jobs.id', 'jobs.title', 'created_at'])
            ->allowedFilters([
                'name',
                'created_at',
            ])
            ->allowedIncludes('jobs')
            ->allowedSorts([
                'name',
                'created_at',
            ])
            ->paginate($request->integer('per_page', 15));

        return CompanyData::collect($companies, PaginatedDataCollection::class);
    }
}

  10. Create an OpenAPI operation extension

    OpenAPI operation extensions allow you to add or modify information about a route's documentation (the 'operation' in OpenAPI terms). To create one, extend the \Dedoc\Scramble\Extensions\OperationExtension class and implement the handle method. The handle method receives the operation instance and a route info object, allowing you to mutate the operation based on the route's AST or metadata.

  11. Automatically document Spatie Laravel Query Builder with Scramble PRO

    Scramble PRO automatically generates OpenAPI documentation for query parameters (filters, sorts, fields, and includes) based on the configuration of Spatie's Laravel Query Builder. It supports query builders defined directly in route actions, custom classes extending QueryBuilder, or methods called within route actions.

  12. Integrate Scramble PRO with Laravel Actions

    Scramble supports lorisleiva/laravel-actions as part of the Scramble PRO package. Once Scramble PRO is installed and routes are configured, Scramble automatically generates operation documentation by analyzing Laravel Action classes, including those using asController or handle methods.