07. Swagger

Accessing the Documentation

This repository already includes the Swagger-UI files, located in the /public/swagger directory.

So to access the interface, enter:

http://localhost/api/docs

There's a redirect configured in the /routes/api.php file points the path above to the Swagger-UI.

Generating the Documentation

The command composer swagger:generate uses the file ./swagger.php to load constants to be use in the PHP Attributes.
The constants have a default value and can be set through variables in .env file.

$constants = [
    'APP_NAME'    => getenv('APP_NAME') ?: 'Laravel App',
    'APP_VERSION' => getenv('APP_VERSION') ?: '1.0',
    'APP_URL'     => getenv('APP_URL') ?: 'http://laravel-app.local'
];

The command will generate the OpenAPI specification file and save it here: /public/swagger.yaml.

Basic Information

Since the version of swagger-php installed in this repository uses PHP Attributes (Available since PHP 8.1) to generate the OpenAPI specification, all the basic information, such as title, version, url and tags are defined in a dummy class located in /app/Swagger/Application.php.

This is a great place to add documentation for things that are note related to the endpoints and entities, like tags, security and authentication.

References

• Swagger Specification: Serialization
• Swagger Specification: Authentication
• swagger-php: Common Techniques
• swagger-php: Examples PHP 8.1
• swagger-php: Examples PHP 8.1
• Documentação swagger em aplicações PHP
• Security Annotations in Swagger-PHP
• swagger-php response array of objects using attributes
• How to define an enum in OpenAPI (Swagger)?
• Issue 'Authorization: Bearer ' in a Swagger openAPI Annotations