The Hassle-Free automatic API documentation generation for Laravel.
A Swagger alternative.
Supports Open API 3.0.0

Try latest DEMO!

Fast Install on any Laravel Project

Hassle Free Auto Generate API Documentation for request rules and parameters

Analyze Inbuilt SQL query time analyzer, response time and headers output.

Supports Postman and OpenAPI 3.0.0 exports.

Features

• Light and Dark mode
• Automatic rules fetching from injected Request and by regexp
• Automatic routes fetching from Laravel Routes
• Support for Laravel logs
• Support for SQL query and query time
• Support for HTTP response time and memory consumption
• Support for Authorization Headers
• Support for File uploads
• Support for Eloquents events
• Display extra documentation using markdown
• Saves history previous requests
• Added filters to sort, group and filter routes by methods, controllers, middlewares, routes
• Export Laravel API, routes, rules and documentation to Postman and OpenAPI 3.0.0

Read on Medium

Automatically generate API documentation for Laravel without writing annotations.

Read more: https://medium.com/web-developer/laravel-automatically-generate-api-documentation-without-annotations-a-swagger-alternative-e0699409a59e

Requirements

Lang	Versions
PHP	8.0 or 8.1 or 8.2
Laravel	8.* or 9.* or 10.*

Installation

You can install the package via composer:

composer require rakutentech/laravel-request-docs

You can publish the config file with:

php artisan vendor:publish --tag=request-docs-config
php artisan route:cache

# Optional publish assets
# php artisan vendor:publish --tag=request-docs-assets

(optional) Add the following middleware to your API, so that the SQL logs and model events are captured.

app/Http/Kernel.php

        'api' => [
            ...
            \Rakutentech\LaravelRequestDocs\LaravelRequestDocsMiddleware::class,
            ... and so on

Usage

Dashboard

View in the browser on /request-docs/

Design pattern

For this plugin to work, you need to follow the design pattern by injecting the request class inside the controller. For extra documentation you can use markdown inside your controller method as well.

Screenshots

Dark and Light Modes

• Uses local storage to save the history of previous requests and request headers.
• Request, SQL, response and events timeline below:

Settings to sort, group and filter

Extra documentation

You can write extra documentation in markdown using @lrd in the PHPDoc on the rules method of the Request classes and on the controller methods.
This will then be rendered as HTML on the dashboard.
Documentation defined on the controller method is appended below documentation defined on the rules method.
Example of using it in the controller:

    /**
     * @lrd:start
     * # Hello markdown
     * Free `code` or *text* to write documentation in markdown
     * @lrd:end
     */
    public function index(MyIndexRequest $request): Resource
    {

Route grouping

You can add a @LRDtag parameter to the description of your controller to group the routes on the dashboard. Endpoint grouping is still done by routes and these tag will only be used as a friendly name for viewing the dashboard. @LRDTags is used to generate documentation in OpenAPI format Example of using it in the controller:

    /**
     * Class DemoController
     * @package App\Http\Controllers
     * @LRDtag Demonstration
     * Demonstration management endpoint
     */
     class DemoController extends Controller
     {

Endpoint summary and description

The LRD extracts the summary and description of the PHPDoc endpoint from the controller method, this information is rendered as a summary and description of the routes in the LRD dashboard.
To extract this information, the standard established by Laravel's PHPDoc is used, where the first line of the PHPDoc is the summary and the rest of the PHPDoc is the description until a tag with @ PHPDoc documentation . Summary and description are used to generate documentation in OpenAPI format

    /**
     * Summary of method.
     * Description of method
     * @param MyIndexRequest $request
     */
    public function index(MyIndexRequest $request): Resource
    {

Extra parameters

You define extra parameters using @LRDparam.
You can use @LRDparam in PHPDoc on both the rules methods and the controller methods.
You can also overwrite rules using @LRDparam. Meaning, when rules are defined in the rules method, you can overwrite those rules using @LRDparam in the PHPDoc above the rules method. And you can overwrite those rules using @LRDparam in a PHPDoc on the controller methods.
So, the precedence is Controller method PHPDoc < Rules method PHPDoc < Rules method values.

    /**
     * @LRDparam username string|max:32
     * // either space or pipe
     * @LRDparam nickaname string|nullable|max:32
     * // override the default response codes
     * @LRDresponses 200|422
     */
    public function index(MyIndexRequest $request): Resource
    {

Rules and field description and example

To obtain a description of the fields and rules you can add a fieldDescriptions() method to your formRequest and return an associative array where the key is the name of the field and the value is the description and example of the field. This method is not required, if it is not found, the descriptions will not be added. The examples are only used for documentation and are not used for sending the request. Descriptions and examples are used to generate documentation in OpenAPI format

    class UserRequest extends FormRequest
    {
    /**
     * Get the validation rules that apply to the request.
     */
    public function rules(): array
    {
        return [
            'name' => 'required|string|max:50',
            'password' => 'string|min:8|max:100|',
            'remember' => 'required|boolean|required_if',
        ];
    }
    
    /**
     * Provides a detailed description of the expected parameters
     * in the body of an HTTP request.
     */
    public function fieldDescriptions(): array
    {
        return [
            'name' => 'Name of user'
            'password' => 'The password of the user being created',
            'remember' => 'Whether or not the user should be reminded'
        ];
    }

Rule order

The order of the rules that will be displayed in the documentation will be changed to the rule registered in the rules method as a way of maintaining the display standard. If not informed, the display rule will be the same as the rules method. It is recommended that nullable be inserted at the end of the rules to correctly present the description or null

    'rules_order' => [
        'required',
        'required_if',
        'file',
        'integer',
        'string',
        'bool',
        'date',
        'file',
        'image',
        'array',
        'min',
        'max',
        'nullable',
    ]

Response codes

Without explicitly declaring response codes, all routes are documented to return any of the response codes defined in the request-docs.php default_responses configuration.
However, using @LRDresponse 200|422 (spaces or pipes) within the PHPDoc on your controller methods, you are able to explicitly define what status codes can be returned by the server.

Configuration

Please view the request-docs.php config file to see how you can customise your experience.

Use Factory to example

To generate an example based on the project's factories, the use_factory option must be enabled in the project file. settings. This way, the examples will be generated based on the output of your model's factories.

Remove factory fields in examples

To ensure that a field is not generated in the example, it can be inserted as a new value in the exclude_fields configuration array, this way this field will be removed when the example is generated, ensuring correct display

'exclude_fields' => [
    'password',
    'remember_token',
], 

Testing

./vendor/bin/phpunit

Linting

./vendor/bin/phpcs --standard=phpcs.xml --extensions=php --ignore=tests/migrations config/ src/

Fixing lints

./vendor/bin/php-cs-fixer fix src/
./vendor/bin/php-cs-fixer fix config/

Star History

Changelog

• Initial Release
• v1.9 Added improvements such as status code, response headers, custom request headers and fixed issues reported by users
• v1.10 Show PHP memory usage, gzip encoding fix
• v1.12 Bug fix of id, and Laravel 9 support
• v1.13 Laravel 9 support
• v1.15 Adds Filter and fall back to regexp upon Exception
• v1.17 Do not restrict to FormRequest
• v1.18 Fix where prism had fixed height. Allow the text area resize.
• v1.18 Updated UI and pushed unit tests
• v1.19 Exception -> Throwable for type error
• v1.20 Feature support open api 3.0.0 #10
• v1.21 Ability to add custom params
• v1.22 Boolean|File|Image support
• v1.22 Boolean|File|Image support
• v1.23 Bug fix for LRD doc block #76
• v1.27 A few fixes on width and added request_methods
• v2.0 UI Renewal to React Static
  • @QAParam is now @LRDparam
  • No special changes for users, upgrade to v2.x as usual
  • Upgrading users will need to republish config
• v2.1 UI - adds search bar and few alignment fixes on table
• v2.2 PHP 8.1 and 8.2 support added - Groupby enabled for routes and controllers
• v2.3 Bug fix for local storage (tabs) and full UI refactored after alpha
• v2.4 Show version on navbar and curl is using ace editor
• v2.5 Groupby final fix and local storage clear button. Other UI refactor
• v2.6 File uploads
• v2.7 Show activity on Eloquent models
• v2.8 Show full activity on Eloquent models
• v2.13 Bug fixes, and nested params support
• v2.14 Adds path params support
• v2.16 Top Navbar is fixed
• v2.19 Publish _astro assets
• v2.25 laravel-request-docs:export command to export
• v2.28 Allow extra documentation to be defined on the rules method of the Request class. By @Ken-vdE
• v2.31 Customized title, vup js and PHP to latest. Customized headers. Save response history.

Contributors