Openapi3 Examples Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require --dev mermade/openapi3-examples
   

   Add to composer.json under require-dev if not using globally.

2. Locate Examples The package provides test cases in:

   • vendor/mermade/openapi3-examples/src/Examples/ (for valid/invalid OpenAPI specs)
   • vendor/mermade/openapi3-examples/tests/ (for validator test cases)

3. First Use Case: Validating a Spec Use with a validator like zircote/swagger-php:

   use Mermade\OpenApi3Examples\Examples\ValidSpecs;
   use Zircote\Swagger\Validator;
   
   $validator = new Validator();
   $spec = ValidSpecs::getPetstoreSpec(); // Example valid spec
   $validation = $validator->validate($spec);
   

Implementation Patterns

Workflow: Testing API Specs

1. Unit Testing OpenAPI Use examples in PHPUnit tests:

   use Mermade\OpenApi3Examples\Examples\InvalidSpecs;
   
   public function testInvalidSpec()
   {
       $validator = new Validator();
       $spec = InvalidSpecs::getMissingTitleSpec();
       $this->assertFalse($validator->validate($spec)->isValid());
   }
   

2. Integration with CI Add to phpunit.xml:

   <testsuites>
       <testsuite name="OpenAPI Validation">
           <directory>./tests/OpenApi</directory>
       </testsuite>
   </testsuites>
   

3. Dynamic Example Loading Load specs dynamically in Laravel:

   use Mermade\OpenApi3Examples\Examples\ValidSpecs;
   
   $specs = collect(ValidSpecs::getAllValidSpecs())
       ->map(fn ($spec) => json_encode($spec, JSON_PRETTY_PRINT));
   

Patterns for Extending

• Custom Validators: Extend Zircote\Swagger\Validator and use examples to test edge cases.
• Documentation: Reference examples in API docs (e.g., Swagger UI) to show valid/invalid formats.

Gotchas and Tips

Pitfalls

1. Version Mismatch The package uses OpenAPI 3.x. Ensure your validator (e.g., zircote/swagger-php) supports 3.x:

   composer require zircote/swagger-php:^7.0
   

2. False Positives/Negatives Some examples may trigger validator quirks. Cross-check with Swagger’s validator.

3. Namespace Conflicts Avoid naming collisions with Mermade\OpenApi3Examples in your project.

Debugging Tips

• Inspect Validation Errors:

  $validation = $validator->validate($spec);
  foreach ($validation->errors() as $error) {
      logger()->error($error->getMessage());
  }
  

• Compare with Editor: Use Swagger Editor to manually validate specs.

Extension Points

1. Add Custom Examples Extend the package by creating a new class:

   namespace App\OpenApiExamples;
   
   use Mermade\OpenApi3Examples\Examples\BaseSpecs;
   
   class CustomSpecs extends BaseSpecs {
       public static function getCustomSpec() { ... }
   }
   

2. Mock API Responses Use examples to mock responses in Laravel tests:

   $response = json_decode(file_get_contents(
       __DIR__ . '/../../vendor/mermade/openapi3-examples/src/Examples/ValidSpecs/petstore.json'
   ));
   

3. Laravel Service Provider Register examples as a singleton for global access:

   $this->app->singleton('openapi-examples', fn () => new ValidSpecs());