Download the PHP package gungcahyadipp/auto-docs without Composer

Auto-Docs

All-in-one API documentation package for Laravel. Bundles Scramble and Scramble Pro into a single package with automatic configuration, Bearer token auth, dark theme UI, and external docs support.

Features

• Zero-config API documentation generation from your Laravel code
• Dark theme UI by default with Stoplight Elements
• Bearer JWT authentication auto-configured
• External markdown docs — separate endpoint descriptions from controller code
• Multi-version API support (V1, V2, etc.) with conflict detection
• Conditional extension loading for optional packages (Laravel Data, Query Builder, JSON:API, Laravel Actions)
• Single unified config file (autodocs.php)

Versions Bundled

• dedoc/scramble v0.13.13
• dedoc/scramble-pro v0.8.7

Installation

The package auto-discovers via Laravel's package discovery. No manual provider registration needed.

Configuration

Publish the config file:

Publish the API description markdown:

Publish everything at once:

Usage

Visit /docs to see the generated API documentation.

The JSON OpenAPI spec is available at /docs/api.json.

Config Overview

All configuration lives in config/autodocs.php:

Security Scheme

Bearer JWT is enabled by default. All endpoints will show the lock icon in the docs UI.

To exclude an endpoint from authentication, use @unauthenticated in the PHPDoc:

To switch to API Key authentication:

To disable security entirely:

External Docs (Separated Descriptions)

Instead of writing long descriptions in your controller PHPDoc, you can create separate markdown files. No changes needed in your controller — the extension automatically matches doc files to endpoints based on controller name and method.

Quick Start

1. Generate the skeleton:

2. Edit the generated .md files in autodocs/

3. Visit /docs — descriptions are loaded automatically

How It Works (No Controller Changes Needed)

Given this controller:

And this file:

The docs UI will automatically show the content from store.md as the endpoint description. You don't need to add any annotation, attribute, or PHPDoc to the controller.

Combining with PHPDoc

If you still want to use PHPDoc for some things (like @unauthenticated or @tags), that works fine:

The description_strategy config controls how external docs interact with any existing PHPDoc description.

File Structure

Markdown Format

• First line (or # heading) becomes the summary/title
• Everything after the first blank line becomes the description

Path Resolution

For a controller like App\Http\Controllers\Api\V1\UserController@store, the extension searches these paths in order:

1. autodocs/Api/V1/UserController/store.md (most specific)
2. autodocs/V1/UserController/store.md
3. autodocs/UserController/store.md (only if no V1/V2 conflict)
4. autodocs/Api/V1/User/store.md (without "Controller" suffix)
5. autodocs/User/store.md

Multi-Version Safety

When both V1/UserController/ and V2/UserController/ exist in your docs folder, the short name fallback (UserController/store.md) is automatically disabled to prevent cross-version contamination.

Description Strategy

Control how external docs interact with PHPDoc in your controllers:

API Description (Homepage)

The API homepage description is loaded from a markdown file:

1. Default: bundled template from the package
2. After publish: autodocs/description.md

Edit this file to customize the description shown on the docs homepage.

Optional Package Support

Auto-Docs conditionally enables extensions for these packages when installed:

No configuration needed — just install the package and docs are generated automatically.

Custom Extensions

Register your own Scramble extensions:

Or programmatically in a service provider:

Auto-Generate Docs Skeleton

Automatically scaffold markdown doc files for all your API endpoints:

This scans all registered API routes and creates .md files with a ready-to-fill template:

Options

Example

Each generated file includes:

• Auto-generated title based on method name (e.g. "List all users", "Create a new order")
• HTTP method and URI as comment
• Placeholder sections for authentication, request body, and response

Testing

License

MIT