Automatically generate beautiful API documentation for your Laravel API routes using annotations.
Installation
PHP 7.4 and Laravel 7 or higher are required.
Install LaRecipe
You will need LaRecipe to serve your autogenerated markdown
composer require binarytorch/larecipe
Then run
php artisan larecipe:install
Install LaDocumenter
After installing LaRecipe you can now install LaDocumenter
composer require icodestuff/ladocumenter
Then 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.