Download the PHP package jkbennemann/laravel-api-documentation without Composer

Laravel API documentation

This library is currently in an alpha phase

• still under development
• versions are not stable
• breaking changes can occur

This is an opinionated package to generate API documentation for Laravel applications. They key focus is to remove the need to manually write documentation and keep it up to date by generating it from the code.

Installation

You can install the package via composer:

You can publish the config file with:

By default it will set the settings to the following:

• Ignore all routes that are registered by a vendor package
• Ignore all routes with HTTP methods HEAD, OPTIONS
• UIs for swagger or redoc are disabled
• If enabled the UIs are available at
  • /documentation (defaults to swagger)
  • /documentation/redoc (if enabled)
  • /documentation/swagger (if enabled)

Linking the storage's public directory

The package will store the generated documentation at the defined disk.
By default it will use the public disk to store the documentation. For the default Laravel disk of public you'd need to link the storage folder to make it accessible by running:

This will ensure that the generated documentation is accessible.
When generating the documentation the package (by default) will store the documentation at storage/app/public/api-documentation.json.

In order for this to work you need to have the public disk configured in your config/filesystems.php.
This should be already configured by default by your application.

As the documentation is stored in the storage folder of your application which by default will not be added to the VCS
it is needed to explicitly exclude the api-documentation.json from your storage/app/public/.gitignore file.

If you want to make the documentation public by default, without the need to link the storage folder, you can:

1. Add a dedicated disk configuration for the documentation to config/filesystems.php (Recommended)
2. Adjust the default disk configuration to not use the storage_path() (Not recommended)

and then using the disk public_exposed in the config/laravel-api-documentation.php file.

Useful tips

If you want to automatically re-generate the documentation all the time, consider to add a git hook to your repository.
This way you allow the documentation to be kept up-to-date, every time you push changes to your repository.

Generating the documentation

bash php artisan documentation:generate json { "scripts": { "documentation:generate": [ "@php artisan documentation:generate" ] } } json { //... "\/login": { "post": { "tags": [ "Authentication" ], //... } } } json { //... "\/login": { "post": { "summary": "Login a user", //... } } } json { //... "\/login": { "post": { "description": "Logs an user in.
This route requires a valid email and password.", //... } } } json { //... "\/login": { "post": { "externalDocs": { "url": "https://example.com/docs", "description": "External documentation" } //... } } } json { //... "\/login": { "post": { //... "responses": { "200": { "description": "Logged in user information", "headers": { "X-Token": { "description": "Token for the user to be used to issue API calls", "schema": { "type": "string" } } }, "content": { "application\/json": { "schema": { //data of the UserResource.php } } } }, "401": { "description": "Failed Authentication", "headers": {}, "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } //... } } }

### Request/Resource attributes

For request or resource classes the same attributes can be used as for the routes, except for the `Tag` attribute.  
In addition to that the following attributes are available:

#### 1. Parameter
This attribute can be used to specify additional information about a parameter.

Available parameters:
- (required) `name` (string) - The name of the parameter
- `required` (boolean) - Whether the parameter is required or not; *default:`false`*
- `description` (string) - A description of the parameter; *default:`''`*
- `type` (string) - The type of the parameter; *default:`'string'`*
- `format` (string) - The format of the parameter, considered as the sub-type as of OpenAPI; *default:`null`*
- `example` (mixed) - An example value for the parameter; *default:`null`*
- `deprecated` (boolean) - Whether the parameter is deprecated or not; *default:`false`*

## Roadmap
- [ ] Add support providing examples for request
- [ ] Add support for handling inline controller validation rules
- [ ] Adjusting the logic to determine the response structure with its types and formats correctly
- [ ] Option to customize the location of the generated documentation file
  -  [ ] Support for external storages (eg. Github Link, S3 Bucket, ...)
- [ ] ...

## Security Vulnerabilities

Please review [our security policy](../../security/policy) on how to report security vulnerabilities.

## Credits

- [Jakob Bennemann](https://github.com/jkbennemann)
- [All Contributors](../../contributors)

## License

The MIT License (MIT). Please see [License File](LICENSE.md) for more information.