Related Projects

Projects that work with L5-Swagger.

openapi-introspector

openapi-introspector builds the documentation from the application's routes. Every route in the api middleware group appears in the document with its path parameters, before a single attribute is written. Attributes add to a route's operation where the description matters, for example responses and request bodies.

It also adds what a route's middleware and parameters imply: a 401 and security requirements behind auth, a 404 for a parameter bound to a model, and the input and 422 of a form request.

It uses the builder_factory scan option, added in L5-Swagger 11.2.1:

composer require radebatz/openapi-introspector

In config/l5-swagger.php, under defaults:

'scanOptions' => [
    'builder_factory' => \Radebatz\OpenApi\Introspector\Integrations\L5Swagger\BuilderFactory::class,
],

How to choose the routes, map guards to security schemes and customise the factory is in the introspector's L5-Swagger guide.

openapi-router

openapi-router registers the Laravel routes from the attributes that document them, so the routes and the documentation cannot drift apart. It is the other direction from openapi-introspector: the attributes come first, and the routes follow from them.

It reads swagger-php's spec attributes (OpenApi\Spec) only, so L5-Swagger needs the mode scan option set to hybrid or spec, see Modes.

composer require radebatz/openapi-router

How to register the routes and cache them is in the router's README.

openapi-verifier

openapi-verifier checks the responses in a project's tests against the documentation. A response that does not match its documented schema fails the test. It works with any documentation L5-Swagger generates, with or without the projects above.

composer require --dev radebatz/openapi-verifier

In a test case, with L5-Swagger's default paths:

use Radebatz\OpenApi\Verifier\Adapters\Laravel\OpenApiResponseVerifier;

class UsersTest extends TestCase
{
    use OpenApiResponseVerifier;

    protected function setUp(): void
    {
        parent::setUp();

        $this->registerOpenApiVerifier(null, storage_path('api-docs/api-docs.json'));
    }
}

The documentation has to be generated before the tests run. The other adapters and how responses are matched are in the verifier's README.