PHPackages yeab/laravel-api-contract - 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. yeab/laravel-api-contract ActiveLibrary[API Development](/categories/api) yeab/laravel-api-contract ========================= Define API contracts in your Laravel application and generate TypeScript types, API clients, SDKs, OpenAPI specs, Postman collections, and more. v1.1.0(1mo ago)03MITPHPPHP ^8.2CI passing Since Jul 10Pushed 1mo ago1 watchersCompare [ Source](https://github.com/yeab-B/laravel-api-contract)[ Packagist](https://packagist.org/packages/yeab/laravel-api-contract)[ RSS](/packages/yeab-laravel-api-contract/feed)WikiDiscussions main Synced 2w ago READMEChangelogDependencies (12)Versions (3)Used By (0) Laravel API Contract ==================== [](#laravel-api-contract) The ultimate "Write once. Generate everything." toolkit for Laravel APIs. [ ![Latest Version on Packagist](https://camo.githubusercontent.com/ea9bc88f6dbf7ee86fdb08bc991b2a513650a8e0773730953a2ee31b89572de5/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f796561622f6c61726176656c2d6170692d636f6e74726163742e7376673f7374796c653d666c61742d737175617265) ](https://packagist.org/packages/yeab/laravel-api-contract) [ ![Total Downloads](https://camo.githubusercontent.com/5cffab6c4f5c00460f08a05fafc24c55ad2eff7394ec46994d8341bc9d36869d/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f796561622f6c61726176656c2d6170692d636f6e74726163742e7376673f7374796c653d666c61742d737175617265) ](https://packagist.org/packages/yeab/laravel-api-contract) [ ![Build Status](https://camo.githubusercontent.com/b159cc76dc51087dd343b47b3c81d13ec1ee5656c9eee26b8eac0a328e82ae14/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f796561622d422f6c61726176656c2d6170692d636f6e74726163742f74657374732e796d6c3f6272616e63683d6d61696e267374796c653d666c61742d737175617265) ](https://github.com/yeab-B/laravel-api-contract/actions) [ ![License](https://camo.githubusercontent.com/3abbefcbbf88ff439b4b0c1630e66860739eafc10ee94913c8df445613689059/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f796561622f6c61726176656c2d6170692d636f6e74726163742e7376673f7374796c653d666c61742d737175617265) ](https://packagist.org/packages/yeab/laravel-api-contract) --- πŸ“– Introduction -------------- [](#-introduction) **Laravel API Contract** is an advanced, fully automated architecture utility for Laravel applications. It statically analyzes your existing Laravel routes, controllers, Form Requests, and API Resources to automatically generate a comprehensive **API Contract**. From this single source of truth, it instantly generates Swagger documentation, TypeScript interfaces, typed API clients, Postman collections, Markdown docs, PHPUnit feature tests, and backwards-compatibility reports. 🎯 Core Philosophy ----------------- [](#-core-philosophy) **"Write once. Generate everything."** You shouldn't have to write your validation rules in a Form Request, duplicate them in OpenAPI annotations, and then write them *again* as TypeScript interfaces for your frontend. Laravel API Contract eliminates this friction. Write clean, standard Laravel code, and let the package do the rest. πŸ’‘ Why This Package Exists ------------------------- [](#-why-this-package-exists) Building APIs usually means maintaining parallel systems. When you update an endpoint in your controller, you also have to update your Postman collection, notify the frontend team to update their types, fix the Swagger annotations, and write the tests. This causes friction, drift, and broken integrations. We built this package to ensure that your Laravel code is the *only* source of truth. πŸ› οΈ Problems It Solves --------------------- [](#️-problems-it-solves) - **Documentation Drift:** Your OpenAPI/Swagger docs are never out of sync with your code because they are generated *from* your code. - **Frontend/Backend Friction:** Frontend developers get fully typed API clients and TypeScript interfaces automatically. - **Breaking Changes:** The built-in contract comparator warns you if you accidentally introduce a breaking change to your API. - **Testing Fatigue:** Automatically scaffolds PHPUnit feature tests for every detected endpoint. ✨ Features ---------- [](#-features) - 🧠 **Zero Annotations Required:** Uses static analysis via Reflection and AST parsing. No ugly docblocks or attributes cluttering your controllers. - ⚑ **Blazing Fast:** Intelligent file caching and optimal Reflection usage ensures it analyzes large APIs in milliseconds. - πŸ”’ **Secure by Default:** Hardened against path traversal with strict directory write rules. - πŸ”„ **Intelligent Diffing:** Compares versions of your API and outputs detailed breaking-change reports. - πŸš€ **Framework Native:** Integrates seamlessly into the Laravel ecosystem. Feels like a core component. πŸ—οΈ High-Level Architecture Overview ----------------------------------- [](#️-high-level-architecture-overview) 1. **Route Discovery Engine:** Finds all API routes registered in your application. 2. **Controller Analysis Engine:** Inspects your controller methods to determine logic and parameters. 3. **Form Request & Validation Analyzer:** Parses `rules()` to determine expected input payloads and validation states. 4. **API Resource Analyzer:** Parses your `toArray()` methods to determine the exact shape of your JSON responses. 5. **Contract Builder:** Merges all analyzed metadata into a single, unified `ApiContract` JSON representation. 6. **Generators:** Consumes the `ApiContract` to emit various artifacts. πŸ“¦ Generated Outputs ------------------- [](#-generated-outputs) Once your application is analyzed, you can generate: - **Swagger/OpenAPI (v3.0):** Ready to be served by Swagger UI. - **TypeScript Interfaces:** 100% accurate types matching your Form Requests and API Resources. - **Typed API Client (TypeScript):** A ready-to-use Axios/Fetch service layer for your frontend. - **Postman Collection (v2.1):** Instantly shareable with your team. - **Markdown Documentation:** Beautiful, human-readable markdown for static site generators. - **PHPUnit API Tests:** Automatically scaffolded feature tests for every route. - **Change Reports:** Breaking vs. Non-breaking API change detection over time. πŸ“₯ Installation -------------- [](#-installation) Require the package via Composer. It is recommended to install it as a dev dependency unless you are generating contracts in production: ``` composer require yab/laravel-api-contract --dev ``` Optionally, publish the configuration file: ``` php artisan vendor:publish --provider="Yab\LaravelApiContract\Providers\LaravelApiContractServiceProvider" --tag="config" ``` πŸš€ Quick Start ------------- [](#-quick-start) To instantly analyze your API and build the core contract file (usually written to `storage/api-contract.json`): ``` php artisan api-contract:build ``` Now, you can generate everything else from it! ``` # Generate Swagger Docs php artisan api-contract:swagger --path=public/swagger.json # Generate TypeScript Interfaces php artisan api-contract:typescript --output=resources/ts/types/api.ts # Generate an API Client php artisan api-contract:client --output=resources/ts/services/ # Scaffold PHPUnit Tests php artisan api-contract:tests --output=tests/Feature/Api/ ``` πŸ’» Basic Usage ------------- [](#-basic-usage) The package works automatically by inspecting standard Laravel conventions. ``` // routes/api.php Route::post('/users', [UserController::class, 'store'])->name('users.store'); // app/Http/Controllers/UserController.php public function store(StoreUserRequest $request) { $user = User::create($request->validated()); return new UserResource($user); } // app/Http/Requests/StoreUserRequest.php public function rules() { return [ 'name' => ['required', 'string', 'max:255'], 'email' => ['required', 'email', 'unique:users'], ]; } // app/Http/Resources/UserResource.php public function toArray($request) { return [ 'id' => $this->id, 'name' => $this->name, 'email' => $this->email, ]; } ``` Run `php artisan api-contract:build`, and the package will figure out exactly what `/users` accepts and what it returns! πŸ› οΈ Available Artisan Commands ----------------------------- [](#️-available-artisan-commands) CommandDescription`api-contract:build`Analyze the application and build the central `api-contract.json` file.`api-contract:swagger`Generate an OpenAPI/Swagger v3.0 JSON specification.`api-contract:typescript`Generate TypeScript interface definition files.`api-contract:client`Generate a fully-typed TypeScript API client service.`api-contract:postman`Generate a Postman v2.1 Collection JSON file.`api-contract:docs`Generate human-readable Markdown documentation.`api-contract:tests`Generate boilerplate PHPUnit feature tests.`api-contract:compare`Compare two contract files and output a breaking-change report.πŸ“š Documentation Index --------------------- [](#-documentation-index) For deep dives into configuration and advanced generator options, please refer to the documentation: - [Introduction](docs/introduction.md) - [Configuration Guide](docs/configuration.md) - [Architecture Overview](docs/architecture.md) - [Available Commands](docs/commands.md) - [API Contract Definition](docs/api-contract.md) - [Comparison & Versioning](docs/comparison-and-versioning.md) - [Security & Performance](docs/security-and-performance.md) - [Extending the Package](docs/extending.md) - [Developer Guide](docs/developer-guide.md) - [FAQ](docs/faq.md) - [Glossary](docs/glossary.md) πŸ—ΊοΈ Roadmap ---------- [](#️-roadmap) - Support for Data Transfer Objects (DTOs) parsing (Spatie Data). - Enum parsing for strict typing in Swagger and TypeScript. - Support for generating Nuxt 3/Vue 3 composables. 🀝 Contributing -------------- [](#-contributing) We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for details. ### Security Vulnerabilities [](#security-vulnerabilities) If you discover any security-related issues, please email instead of using the issue tracker. πŸ“„ License --------- [](#-license) The MIT License (MIT). Please see [License File](LICENSE) for more information. ### Health Score 39 β€” LowBetter than 84% of packages Maintenance90 Actively maintained with recent releases Popularity3 Limited adoption so far Community7 Small or concentrated contributor base Maturity47 Maturing project, gaining track record Bus Factor1 Top contributor holds 100% of commits β€” single point of failure How is this calculated?**Maintenance (25%)** β€” Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** β€” Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** β€” Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** β€” Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~0 days Total 2 Last Release 49d ago ### Community Maintainers ![](https://avatars.githubusercontent.com/u/166545362?v=4)[Yeabsira Behailu](/maintainers/yeab-B)[@yeab-B](https://github.com/yeab-B) --- Top Contributors [![yeab-B](https://avatars.githubusercontent.com/u/166545362?v=4)](https://github.com/yeab-B "yeab-B (10 commits)") --- Tags apilaravelstatic analysisdocumentationswaggeropenapitypescriptcode-generationcontractPostman ### Code Quality TestsPHPUnit Static AnalysisPHPStan Code StylePHP\_CodeSniffer Type Coverage Yes ### Embed Badge ![Health badge](/badges/yeab-laravel-api-contract/health.svg) ``` [![Health](https://phpackages.com/badges/yeab-laravel-api-contract/health.svg)](https://phpackages.com/packages/yeab-laravel-api-contract) ``` ### Alternatives [laravel/mcp Rapidly build MCP servers for your Laravel applications. 80427.1M249](/packages/laravel-mcp)[psalm/plugin-laravel Psalm plugin for Laravel 3345.4M354](/packages/psalm-plugin-laravel)[api-platform/laravel API Platform support for Laravel 58190.1k21](/packages/api-platform-laravel)[laravel/ai The official AI SDK for Laravel. 1.1k4.6M342](/packages/laravel-ai)[aedart/athenaeum Athenaeum is a mono repository; a collection of various PHP packages 265.2k](/packages/aedart-athenaeum)[roots/acorn Framework for Roots WordPress projects built with Laravel components. 9922.4M148](/packages/roots-acorn) PHPackages Β© 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)