icodestuff/ladocumenter

Automatically generate beautiful API documentation for your Laravel API routes using annotations.

1.0.1 2020-11-24 00:08 UTC

Requires

• php: ^7.4
• minime/annotations: dev-master
• myclabs/php-enum: ^1.7

Requires (Dev)

• nunomaduro/collision: ^4.2
• nunomaduro/larastan: ^0.5.8
• orchestra/testbench: ^5.2
• phpunit/phpunit: ^8.5

MIT

• Solomon Antoine

• documentation
• swagger
• apidoc
• openapi
• documenter
• laravel-api
• api-documentation
• larecipe

README

Automatically generate beautiful API documentation for your Laravel API routes using annotations.

Installation

PHP 7.4 and Laravel 7 or higher are required.

Installing

You will need LaRecipe to serve your autogenerated markdown

run composer require --dev binarytorch/larecipe && composer require --dev icodestuff/ladocumenter to download both LaRecipe and LaDocumenter as a dev dependency

Then php artisan larecipe:install to install Larecipe

And lastly publish the config php artisan vendor:publish --provider="Icodestuff\LaDocumenter\LaDocumenterServiceProvider"

Demo Video

Here is a YouTube video showcasing the LaDocumenter package

Getting Started

The only endpoints that are documented are the ones in your api.php file.

Generating Documentation

In order to compile your annotations to markdown you will need to run:

php artisan ladocumenter:generate

Grouping Endpoints

All endpoints are grouped for easy organization. Only use @Group to group endpoints in a single controller class by adding it to the top of the controller like so:

Example

/**
 * @Group(name="Foo", description="This is an example group.")
 */
class FooController extends Controller
{

}

Attributes

• Name (required)
• Description (optional)

Documenting Endpoints

The @Endpoint annotation is used for a single controller method or endpoint. Note, at this time we don't support closures or resources 😕

Example

class FooController extends Controller
{
    /**
    * @Endpoint(name="Example", description="This is an example endpoint.")
     */
    public function bar()
    {
    
    }
}

Attributes

• Name (required)
• Description (optional)

Specifying Request Parameters

To specify a list of valid parameters your API route accepts, use the @QueryParam or @BodyParam.

Both the @BodyParam & @QueryParam annotation takes the name, type, required, description and an example.

@BodyParam Example

class FooController extends Controller
{
    /**
    * @BodyParam(name="foo", type="string", status="required", description="An example body paramater", example="bar")
     */
    public function bar(FormRequest $request)
    {
    
    }
}

@QueryParam Example

class FooController extends Controller
{
    /**
    * @QueryParam(name="foo", type="string", status="optional", description="An example query paramater", example="bar")
     */
    public function bar()
    {
    
    }
}

Attributes

• Name (required)
• Type (required)
• IsRequired (required)
• Description (optional)
• Example (optional)

Generating Responses

To generate a response, you must use the @ResponseExample annotation. This takes in the status of the response as well as a link to the response file like so:

class FooController extends Controller
{
    /**
    * @ResponseExample(status=200, file="responses/example.json")
     */
    public function bar()
    {
        return response()->json(['foo' => 'bar']);
    }
}

Attributes

• Status (required)
• Example (required)

Be sure to add your responses to the storage directory as that is where LaDocumenter looks for them. We recommend automatically generating responses using Laravel's testing suite.

Indicating Authentication Status

LaDocumenter automatically labels an endpoint as authenticated if the route uses the middleware defined in the config/ladocumenter.php file:

'auth_middleware' => [
    'auth:sanctum',
    'auth'
],

If you are using a separate auth middleware, be sure to define it in the config file.