Documentation
You can access comprehensive customization options to enrich the documentation, including the ability to incorporate your own custom routes, for instance.
Generating documentation
Each time you need to update the documentation, you have to run the rest:documentation command:
php artisan rest:documentation
The documentation is generated based on registered routes, if you don't expose all the routes on a certain Rest Resource, they won't appear in the documentation.
Keep in mind that the documentation will be stored in your public folder and be git committed. Avoid updating your documentation directly on production servers. Instead, update it locally during development.
By default, the generated documentation will be accessible via /api-documentation. If you want to customize this or disable it, change your rest.routing documentation.
Configure data
To achieve this, you need to be familiar with OpenApi. If you aren't, please consult the documentation
You can to configure OpenApi information, servers and security in the configuration:
[
/*
|--------------------------------------------------------------------------
| Rest Documentation
|--------------------------------------------------------------------------
|
| This is the feature that automatically generates your API documentation for you.
| Laravel Rest Api will validate each searched / mutated / deleted model to avoid leaks in your API.
| This feature is based on OpenApi, for more details see: https://swagger.io/specification/
|
*/
'documentation' => [
'info' => [
'title' => config('app.name'),
'summary' => 'This is my projet\'s documentation',
'description' => 'Find out all about my projet\'s API',
'termsOfService' => null, // (Optional) Url to terms of services
'contact' => [
'name' => 'My Company',
'email' => 'email@company.com',
'url' => 'https://company.com'
],
'license' => [
'url' => null,
'name' => 'Apache 2.0',
'identifier' => 'Apache-2.0'
],
'version' => '1.0.0'
],
// See https://spec.openapis.org/oas/v3.1.0#server-object
'servers' => [
[
'url' => '/', // Relative to current
'description' => 'The current server'
],
// [
// 'url' => '"https://my-server.com:{port}/{basePath}"',
// 'description' => 'Production server',
// 'variables' => [
// 'port' => [
// 'enum' => ['80', '443'],
// 'default' => '443'
// ],
// 'basePath' => [
// 'default' => 'v2',
// 'enum' => ['v1', 'v2'],
// ]
// ]
// ]
],
// See https://spec.openapis.org/oas/v3.1.0#security-scheme-object
'security' => [
// [
// 'type' => 'http',
// 'description' => 'description',
// 'scheme' => 'Bearer',
// 'bearerFormat' => 'JWT'
// ],
// [
// 'type' => 'oauth2',
// 'flows' => [
// 'authorizationCode' => [
// 'scopes' => ['write:pets'],
// 'tokenUrl' => 'https://example.com/api/oauth/token',
// 'authorizationUrl' => 'https://example.com/api/oauth/dialog',
// 'refreshUrl' => 'https://example.com/api/oauth/refresh',
// ]
// ]
// ]
]
]
]
Extend the routes
To achieve this, you need to be familiar with OpenApi. If you aren't, please consult the documentation
If, for any reason, you need to change an operation, you can extend the corresponding operation on your controller:
namespace App\Rest\Controllers;
class UsersController
{
/**
* Extend "detail" documentation operation
* @param Operation $operation
* @return Operation
*/
public function generateDocumentationDetailOperation(\Lomkit\Rest\Documentation\Schemas\Operation $operation): Operation
{
return $operation
->withTags(['my custom tag']);
}
}
All the available methods are: generateDocumentationDetailOperation, generateDocumentationSearchOperation, generateDocumentationMutateOperation,
generateDocumentationActionsOperation, generateDocumentationDestroyOperation, generateDocumentationRestoreOperation and generateDocumentationForceDeleteOperation.
To define the documentation, Laravel Rest API creates an object for each OpenAPI argument with all its attributes.
Add your own routes
To achieve this, you need to be familiar with OpenApi. If you don't, please consult the documentation
First you'll need to generate a dedicated RestDocumentationServiceProvider class:
php artisan rest:documentation-provider
Then add the freshly generated service provider to your providers in your config/app.php file:
[
/*
|--------------------------------------------------------------------------
| Autoloaded Service Providers
|--------------------------------------------------------------------------
|
| The service providers listed here will be automatically loaded on the
| request to your application. Feel free to add your own services to
| this array to grant expanded functionality to your applications.
|
*/
'providers' => [
// ...
\App\Providers\RestDocumentationServiceProvider::class
]
]
You are then free to declare your own routes in your freshly generated service provider:
/**
* Bootstrap any application services.
*
* @return void
*/
public function boot()
{
Rest::withDocumentationCallback(function (OpenAPI $openAPI) {
$openAPI->withPaths(
[
'myPath' => (new Path)
->withDescription('my custom path')
->withGet(
(new Operation)
->withTags(['Callable'])
->withSummary('You should call this !')
)
]
);
return $openAPI;
});
}
To see all the schemas available and methods please see the git repository.