solomon04/documentation

This package is abandoned and no longer maintained. The author suggests using the icodestuff/ladocumenter package instead.

Generate API Documentation for your Laravel applications using annotations & LaRecipe.

0.3 2020-06-15 03:49 UTC

Requires

• php: ^7.3
• minime/annotations: dev-master

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

Generate Documentation for your REST API

This package allows you to generate documentation for your REST API via annotations. The markdown is then served by LaRecipe to generate beautiful documentation for your API.

Note this package is NOT stable. I've used it for only one of my repo's.

Getting Started

Install LaRecipe

It is mandatory you install the LaRecipe package in order to get the benefits of the API documenter.

Install LaRecipe via composer.

composer require binarytorch/larecipe

Run the install command.

php artisan larecipe:install

Install Documenter

Install Documenter via composer

composer require solomon04/documentation

Publish provider

php artisan vendor:publish --provider="Solomon04\Documentation\DocumentationServiceProvider"

Steps

1. Go to an API controller
2. Add available annotations to the file.
3. Run php artisan docs:generate

Available Annotations:

@Group

The group annotation is used to group endpoints within a single controller class.

Attributes

• Name (required)
• Description (optional)

Example

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

}

@Meta

The meta annotation is used to document a single endpoint. This would be a function within a controller class.

Attributes

• Name (required)
• Href (required)
• Description (optional)

Example

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

@BodyParam

The body param annotation is used to document the available body parameters within a single endpoint request.

Attributes

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

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

The query param annotation is used to document the available query parameters within a single endpoint request.

Attributes

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

Example

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

@ResponseExample

The response example annotation is used to give an example response for an endpoint.

Important Note: Response example file must be stored in the storage/ directory.

Attributes

• Status (required)
• Example (required)

Example

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

Demo Laravel App

View an example of documentation using the Laravel REST API Documenter.

Tutorial

View a video tutorial here