PHPackages                             xentral/laravel-api - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [API Development](/categories/api)
4. /
5. xentral/laravel-api

ActiveLibrary[API Development](/categories/api)

xentral/laravel-api
===================

A laravel package which provides a smooth OAS workflow

0.16.1(1mo ago)549.9k—0%1MITPHPPHP ^8.2CI passing

Since Aug 18Pushed 1mo agoCompare

[ Source](https://github.com/xentral/laravel-api)[ Packagist](https://packagist.org/packages/xentral/laravel-api)[ Docs](https://github.com/xentral/laravel-api)[ RSS](/packages/xentral-laravel-api/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (10)Dependencies (30)Versions (78)Used By (0)

Laravel OpenApi
===============

[](#laravel-openapi)

[![Latest Version on Packagist](https://camo.githubusercontent.com/adf0a2896cd55ee7d16abc5f4a94c31777c92692f716a7a451e95ea850b20647/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f78656e7472616c2f6c61726176656c2d6170692e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/xentral/laravel-api)[![Total Downloads](https://camo.githubusercontent.com/1cb65f1ff7eaacdee91520d1d1ed91b3502093912636fd96b2241bcf42e0d05e/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f78656e7472616c2f6c61726176656c2d6170692e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/xentral/laravel-api)[![GitHub Actions](https://github.com/xentral/laravel-api/actions/workflows/main.yml/badge.svg)](https://github.com/xentral/laravel-api/actions/workflows/main.yml/badge.svg)

This package provides comprehensive tools for API specification, documentation, and implementation, enabling engineers to build a unified API experience.

Instead of managing YAML or JSON files, you can use strongly-typed PHP attributes to define your API endpoints and schemas directly alongside the responsible code. The provided attributes work seamlessly with the extended `QueryBuilder` from the `spatie/laravel-query-builder` package to provide a straightforward way of implementing your specified API endpoints.

There were six main goals in mind when creating this package:

- Reduce the required boilerplate as much as possible
- Co-locate endpoint specifications to controllers, validation specifications to request classes, and schema specifications to resource classes
- Generate documentation from specification (not implementation), so the schema can be used for test validation
- Provide structured guard rails around API implementation, making it easy to onboard new developers
- Generate OpenAPI schema files that can be used for PHPUnit testing, documentation, and client generation
- Provide a web interface to easily view and interact with the OpenAPI documentation

Key Features
------------

[](#key-features)

- **Flexible Pagination**: Support for simple, table, and cursor pagination with dynamic type switching via headers
- **Type-Safe Attributes**: Strongly-typed PHP attributes for defining endpoints, schemas, and validation
- **Advanced Filtering**: Powerful query filtering with intuitive URL-based syntax
- **Multiple Schema Support**: Generate multiple OpenAPI specifications from different parts of your application
- **Configurable Response Formats**: Choose between snake\_case and camelCase for response field naming
- **Automatic Documentation**: Generate comprehensive OpenAPI documentation directly from your code
- **Built-in Validation**: Automatic request/response validation against your OpenAPI schemas
- **Web Interface**: Interactive documentation browser for testing and exploring your API

How does it work?
-----------------

[](#how-does-it-work)

`xentral/laravel-api` is built upon the excellent `zircote/swagger-php` and `spatie/laravel-query-builder` packages, adding powerful features for Laravel applications.

The package enables you to manage multiple OpenAPI schema files within a single project. Default configuration is handled via the `openapi.php` config file.

The package provides opinionated and straightforward PHP 8 attributes to define OpenAPI specifications directly in your controller methods and request/resource classes. It includes a set of predefined attributes for common HTTP methods (GET, POST, PUT, PATCH, DELETE) that automatically:

- Generate endpoint documentation with proper path parameters
- Document request bodies and validation requirements
- Define response schemas and status codes
- Handle authentication and authorization responses

These attributes extract the necessary information from your code structure, reducing duplication and keeping your API documentation in sync with your implementation.

Installation
------------

[](#installation)

Install the package via Composer:

```
composer require xentral/laravel-api
```

The package will automatically register its service provider and be ready to use.

Usage
-----

[](#usage)

The following sections demonstrate how to define your API endpoints and schemas using PHP attributes.

### Resource Definition

[](#resource-definition)

API resources are defined using the `#[OA\Schema]` attribute. This allows you to specify the properties of your resource, including their types and validation requirements. The example below demonstrates how to define a simple `SalesOrder` resource.

```