mindedge/laravel-api-doc

Automatically parse laravel api routes and store them in an OpenAPI compatible format

0.1.0 2024-06-13 15:48 UTC

Requires

• goldspecdigital/laravel-eloquent-uuid: ^10.0
• laravel/framework: ^10
• symfony/yaml: ^6

Requires (Dev)

• laravel/pint: ^1.6
• phpunit/phpunit: ^9.5.28

MIT

• Jacob Rogaishio

README

Automatically create documentation for Laravel api's off the registered routes and PHPDoc comments

Table of Contents

• Installation
• How it works
• Usage
• Advanced Usage
• License

Installation

You can install the package via composer:

composer require jrogaishio/laravel-api-doc

How it works

Take the below example route url and controller method:

POST Request: /1.0/pages/1234/posts

// PostController.php

/**
 * Create a new post
 * @param PostCreateRequest $request
 * @param int $page_id The page to create this post on
 */
public function create(PostCreateRequest $request, int $page_id)
{
    $post = Post::create([
        'page_id' => $page_id,
        'title' => 'My Sample Post',
        'body' => 'Hello world!',
    ]);

    return response($post, 201);
}

This library will scan the registered Laravel routes, and see that /1.0/pages/1234/posts is registered to PostController@create.

It will then scan the create method definition for route parameters. This is so we always grab the true parameter list even if the PHPDoc comments don't include them.

If the first parameter is an instance of Illuminate\Foundation\Http\FormRequest we will scan the class for a rules() method to build a list of the form/query parameters.

The we will continue parsing the controller create method to get the route parameters. In this example we have $page_id so we will check the PHPDoc comments to grab a description of what this parameter does.

Usage

Basic Usage:

use Jrogaishio\LaravelApiDoc\Doc;

// The base api path (typically the version) to scan for routes
// Doc::generate() defaults to '1.0'
$baseApiPath = '1.0';
$document = Doc::generate($baseApiPath);

// toOpenApi defaults to OpenApi version 3.0.3 and an export type of yaml
echo $document->toOpenApi();

Get the routes as an OpenApi json object:

use Jrogaishio\LaravelApiDoc\Doc;

$document = Doc::generate('1.0');
print_r($document->toOpenApi(format: 'json'));

Get the routes as an OpenApi php array:

use Jrogaishio\LaravelApiDoc\Doc;

$document = Doc::generate('1.0');
print_r($document->toOpenApi(format: 'array'));

Advanced Usage

You can supply a partially pre-filled document to Doc::generate() to set default values

use Jrogaishio\LaravelApiDoc\Doc;
use Jrogaishio\LaravelApiDoc\Global\Document;

$baseDocument = new Document([
    'name' => 'My Awesome Api',
    'description' => 'The Awesome API Documentation',
    'license' => ['name' => '', 'url' => ''],
    'contact' => '[e-mail]',
    'version' => '1.0'
]);
$document = Doc::generate(doc: $baseDocument);

echo $document->toOpenApi();

License

The MIT License (MIT). Please see License File for more information.