Weave Code
Openapi3 Examples Laravel Package
mermade/openapi3-examples
PHP package for working with OpenAPI 3 example objects: generate, load and manage request/response examples, helping you enrich specs and keep sample payloads in sync during API development, docs and testing workflows.
Passing and failing test cases for OpenAPI 3.x validators
Frequently asked questions about Openapi3 Examples
- How do I use this package to validate OpenAPI specs in Laravel?
- This package provides test cases for OpenAPI 3.x validators, not a standalone validator. Pair it with a library like `zircote/swagger-php` and integrate it into Laravel’s service container. Run tests via Artisan commands or CI/CD pipelines to validate specs before deployment.
- Does this work with Laravel’s API documentation tools like Spatie’s OpenAPI?
- Yes, you can use this package to validate OpenAPI specs generated by Laravel tools. For example, run the test cases against specs created by `spatie/laravel-openapi` to ensure compliance before publishing documentation.
- Which Laravel versions and PHP versions are supported?
- The package itself is PHP-only, so it supports any Laravel version (5.5+) as long as your validator library (e.g., `zircote/swagger-php`) is compatible. Check the validator’s docs for PHP version requirements (typically 7.4+ or 8.x).
- Can I customize the test cases for my API’s specific OpenAPI extensions?
- The package provides a foundation of test cases, but you can extend them. Review the included examples, then add custom cases for your API’s unique OpenAPI extensions or edge cases. The modular structure makes this straightforward.
- How do I integrate this into GitHub Actions or Laravel Forge?
- Add a Composer script or CI step to run the validator against your OpenAPI spec. For example, use `composer test-openapi` to trigger validation, then fail the build on errors. Works seamlessly with Laravel Forge’s deployment hooks or GitHub Actions workflows.
- What if my OpenAPI spec fails validation? How do I handle errors?
- The package doesn’t handle errors itself—it relies on your validator library. Configure the validator to output clear messages (e.g., JSON or CLI errors) and integrate them into your workflow. For Laravel, you could log failures or trigger notifications via Laravel’s `Notification` facade.
- Is this package suitable for runtime API validation (e.g., middleware)?
- No, this package is for validating OpenAPI specs *before* runtime, not for validating requests/responses during API execution. Use it in CI/CD or documentation workflows, not as middleware. For runtime validation, consider tools like `openapi-contract-validator`.
- What are the alternatives to this package for OpenAPI validation?
- Alternatives include `zircote/swagger-php` (validator library), `stoplight/spectral` (CLI-based linter), or `openapi-tools/openapi-generator` (for generating clients). This package is unique in providing *test cases* for validating specs, not a full validator itself.
- How do I generate example request/response payloads from OpenAPI specs?
- This package doesn’t generate payloads—it validates specs. For generating examples, use your validator library’s features (e.g., `zircote/swagger-php` can create examples from schemas) or tools like `openapi-generator` with the `examples` option.
- Will this package slow down my CI/CD pipeline if my OpenAPI spec is large?
- The test cases are lightweight, but performance depends on your validator library. Test with a subset of your spec first to benchmark. If using `zircote/swagger-php`, it’s generally fast for specs under 100 endpoints; for larger specs, consider caching or parallel validation.
Weaver
How can I help you explore Laravel packages today?