Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/ans-group/laravel-api-docs
A package to automatically generate openapi v3 documentation for your laravel rest apis
https://github.com/ans-group/laravel-api-docs
api laravel openapi3 php rest
Last synced: about 1 month ago
JSON representation
A package to automatically generate openapi v3 documentation for your laravel rest apis
- Host: GitHub
- URL: https://github.com/ans-group/laravel-api-docs
- Owner: ans-group
- Created: 2022-03-01T09:36:55.000Z (almost 3 years ago)
- Default Branch: master
- Last Pushed: 2022-07-04T06:17:07.000Z (over 2 years ago)
- Last Synced: 2024-11-09T07:24:13.170Z (3 months ago)
- Topics: api, laravel, openapi3, php, rest
- Language: PHP
- Homepage:
- Size: 26.4 KB
- Stars: 0
- Watchers: 14
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- Code of conduct: CODE_OF_CONDUCT.md
- Security: SECURITY.md
Awesome Lists containing this project
README
# Laravel API Docs [Beta]
*Package is still in beta and is not ready for production use*
Automatically generate API documentation for your laravel API's based off your application routes and handy PHP 8 attributes.
## Installation
First, use composer to require the package as below:
```
composer require ukfast/laravel-api-docs
```
Then all we need to do is to register the service provider in the `providers` key in `config/app.php`:
```
UKFast\LaravelApiDocs\ServiceProvider::class,
```
## Usage
Documentation is generated by scanning your routes file and finding controller methods with special endpoint attributes tagged to them.
Whilst you can easily define your own endpoint types, the package comes with some sensible defaults that generally conform to laravel defaults
### Index
The index endpoint is for endpoints that return a paginated list, for example:
```php
use UKFast\LaravelApiDocs\Endpoints;
use App\Http\Resources\PetResource;
use App\Models\Pet;
class PetController
{
#[Endpoints\Index(PetResource::class)]
public function index()
{
return PetResource::collection(Pet::paginate());
}
}
```
### Create
The create endpoint is for endpoints that create a new resource.
```php
use UKFast\LaravelApiDocs\Endpoints;
use App\Http\Resources\PetResource;
use App\Models\Pet;
class PetController
{
#[Endpoints\Create(PetResource::class)
public function store()
{
}
}
```
### Show
The show endpoint shows an individual resource
```php
use UKFast\LaravelApiDocs\Endpoints;
use App\Http\Resources\PetResource;
use App\Models\Pet;
class PetController
{
#[Endpoints\Show(PetResource::class)
public function show()
{
}
}
```
### Update
The update endpoint updates a resource
```php
use UKFast\LaravelApiDocs\Endpoints;
use App\Http\Resources\PetResource;
use App\Models\Pet;
class PetController
{
#[Endpoints\Update(PetResource::class)
public function update()
{
}
}
```
### Destroy
The destroy endpoint deletes a resource
```php
use UKFast\LaravelApiDocs\Endpoints;
class PetController
{
#[Endpoints\Destroy]
public function destroy()
{
}
}
```
## Customising Request and Response Structure
Your API likely has its own format different to the defaults provided by this package. But redefining these is not difficult.
Here's an example of a custom index endpoint:
```php
namespace App\Docs;
use UKFast\LaravelApiDocs\Endpoint;
use Attribute;
#[Attribute]
class Index extends Endpoint
{
public function __construct(protected $resource)
{}
public function response()
{
return [
'data' => [$this->ref($this->resource)],
'meta' => [
'per_page' => 15,
'total_pages' => 10,
'current_page' => 1,
],
];
}
}
```
Endpoint classes can define two methods: `request` and `response` each return a PHP array outlining the request structure.
Calls to `$this->ref` can be passed a class path to a any class with the #[Resource] attribute on it.
For more examples look inside the `src/Endpoints` folder
## Contributing
We welcome contributions to this package that will be beneficial to the community.
You can reach out to our open-source team via **[email protected]** who will get back to you as soon as possible.
Please refer to our [CONTRIBUTING](CONTRIBUTING.md) file for more information.
## Security
If you think you have identified a security vulnerability, please contact our team via **[email protected]** who will get back to you as soon as possible, rather than using the issue tracker.
## Licence
This project is licenced under the MIT Licence (MIT). Please see the [Licence](LICENCE) file for more information.