Laravel Swagger

Laravel Swagger generates REST API documentation by observing your PHPUnit tests. It extracts information from your Request classes and Controller methods during test execution.

To ensure documentation is captured correctly:

1. Use FormRequests: Define validation rules in the rules() method of a FormRequest class. The plugin uses these rules to describe input parameters.
2. Use Dependency Injection: Inject the Request class into your controller methods. If you don't use dependency injection, the "Parameters" block in the documentation will be empty.
3. Write Feature Tests: Create tests that hit your API endpoints (e.g., using $this->json(...)). The plugin intercepts these requests to build the spec.
4. Run Tests: The documentation is built during the test run.

// 1. Request with rules
class UpdateUserDataRequest extends FormRequest {
    public function rules() {
        return ['name' => 'string', 'age' => 'integer'];
    }
}

// 2. Controller using DI
class UserController extends Controller {
    public function update(UpdateUserDataRequest $request) {
        return response('', 204);
    }
}

// 3. Test to trigger documentation generation
public function testUpdate() {
    $this->json('put', '/users/1', ['name' => 'New Name']);
}

Follow these steps to integrate Laravel Swagger into your project:

1. Install via Composer:

   composer require ronasit/laravel-swagger

2. Publish the configuration:

   php artisan vendor:publish --provider=RonasIT\AutoDoc\AutoDocServiceProvider

3. Register the Middleware: Add \RonasIT\AutoDoc\Http\Middleware\AutoDocMiddleware::class to your global HTTP middleware list in bootstrap/app.php.

4. Update your Test Case: Add the \RonasIT\AutoDoc\Traits\AutoDocTestCaseTrait trait to your tests/TestCase.php file.

5. Configure documentation saving: Choose one of two methods:

   • PHPUnit Extension (Legacy): Add RonasIT\AutoDoc\Support\PHPUnit\Extensions\SwaggerExtension to the <extensions> block in phpunit.xml. Note: This method will be removed in PHPUnit 10+.
   • CI/CD Command: Call php artisan swagger:push-documentation after the tests stage in your CI/CD pipeline.

The SwaggerService is the central engine of the package. It works by intercepting HTTP requests and responses to automatically build an OpenAPI 3.1.0 specification.

The Lifecycle:

1. Initialization: It loads configuration from auto-doc.php and initializes a SwaggerDriverContract implementation (defined in your config) to manage temporary data storage.
2. Data Collection: During a request/response cycle, the addData(Request $request, $response) method is called. This method:
   • Parses the URI and HTTP method.
   • Extracts parameters from the Request (including FormRequests, validation rules, and attributes).
   • Extracts schema information and examples from the Response.
   • Reads DocBlock annotations from the controller/request classes to enrich descriptions, summaries, and deprecation status.
3. Persistence: The collected data is saved via the configured driver.
4. Generation: When requested, the service merges all collected path and component data, validates it against the OpenAPI spec, and provides the final JSON/array content.

The SwaggerService supports documenting security requirements (like API Keys or Bearer tokens) by mapping a configured security driver to the OpenAPI securitySchemes component.

To use this, you must define a security driver in your auto-doc configuration and specify which one to use in the security key.

Example Configuration:

// config/auto-doc.php
return [
    'security' => 'api_key_auth', // The key to use from security_drivers

    'security_drivers' => [
        'api_key_auth' => [
            'type' => 'apiKey', // e.g., 'apiKey' or 'mutualTLS'
            'name' => 'X-API-KEY', // The header/query/cookie name
            'in' => 'header', // 'header', 'query', or 'cookie'
        ],
    ],
    // ...
];

When a request is processed, the service checks if the request satisfies the security requirement (e.g., presence of the header) before adding the security requirement to the specific operation in the OpenAPI spec.