Natuurlijk! Hier is een overzicht en stappenplan om een systeem te ontwerpen dat automatisch API-documentatie genereert voor jouw Laravel-project op basis van OpenAPI-specificaties: 1. Doelstellingen en specificaties: - API-versie: 1.0 - Outputformaat: JSON - Automatische updates na wijzigingen in routes, controllers en verzoeken - Authenticatiedetails toevoegen (bijvoorbeeld authenticatie headers) 2. Keuze van tools en pakketten: - Gebruik een Laravel pakket dat OpenAPI specificaties kan genereren en onderhouden, zoals: - "L5-Swagger" (een Laravel wrapper voor Swagger/OpenAPI) - "Laravel OpenAPI" of vergelijkbare pakketten 3. Implementatiestappen: a. Installatie van L5-Swagger: ```bash composer require "darkaonline/l5-swagger" ``` b. Publiceer de configuratie: ```bash php artisan vendor:publish --provider "L5Swagger\L5SwaggerServiceProvider" ``` c. Configuratie aanpassen in `config/l5-swagger.php`: - Stel de outputformaat in op JSON - Definieer de API-versie onder `info`: ```php 'info' => [ 'title' => 'Mijn API', 'version' => '1.0', ], ``` - Voeg authenticatie headers toe onder `components.securitySchemes`: ```php 'components' => [ 'securitySchemes' => [ 'BearerAuth' => [ 'type' => 'http', 'scheme' => 'bearer', 'bearerFormat' => 'JWT', ], ], ], ``` d. Documentatie integreren in controllers: - Gebruik annotations of PHPDoc comments boven je route- of controller-methoden om parameters, responses en beveiliging te beschrijven. - Bijvoorbeeld: ```php /** * @OA\Get( * path="/api/users", * summary="Lijst van gebruikers", * security={{"BearerAuth":{}}}, * @OA\Response(response=200, description="Een lijst van gebruikers") * ) */ public function index() { // ... } ``` e. Automatisch genereren en up-to-date houden: - Gebruik de CLI-commando's van L5-Swagger om de documentatie te genereren: ```bash php artisan l5-swagger:generate ``` - Dit commando leest de annotaties en genereert de JSON OpenAPI-specificatie. - Voeg dit commando toe aan je deployment- of build-pipeline zodat de documentatie telkens wordt bijgewerkt na wijzigingen. 4. Extra functionaliteiten: - Authenticatie headers worden toegevoegd via de `securitySchemes` en door annotaties in de code. - Eventueel kan je een route maken die de gegenereerde JSON-dokumentatie serveert via bijvoorbeeld `/api/documentatie`. 5. Automatisering: - Integreer het genereren van de documentatie in CI/CD pipelines zodat na elke push of merge de documentatie wordt geüpdatet. - Overweeg het automatisch genereren bij elke deploy of door een webhook. Door deze aanpak te volgen, heb je een dynamisch, up-to-date API-documentatiesysteem dat volledig geïntegreerd is met je Laravel project en de OpenAPI-specificaties gebruikt.

Beste collega, Ik help je graag een systeem te ontwerpen voor automatische API-documentatie in je Laravel-project. Hier is een complete oplossing op basis van je specificaties: ## Vereiste Packages Installeer deze packages via Composer: ```bash composer require darkaonline/l5-swagger composer require zircote/swagger-php ``` ## Configuratie ### 1. Swagger Configuratiebestand Publiceer de configuratie: ```bash php artisan vendor:publish --provider "L5Swagger\L5SwaggerServiceProvider" ``` Pas `config/l5-swagger.php` aan: ```php return [ 'default' => 'v1', 'documentations' => [ 'v1' => [ 'api' => [ 'title' => 'API Documentation v1.0', 'version' => '1.0.0', ], 'routes' => [ 'api' => 'api/v1', ], 'paths' => [ 'docs' => storage_path('api-docs/v1'), ], ], ], 'defaults' => [ 'routes' => [ 'docs' => 'api/documentation', ], 'paths' => [ 'docs_json' => 'api-docs.json', 'format_to_use_for_docs' => 'json', ], ], ]; ``` ### 2. Authenticatie Headers Configuratie Voeg toe aan je Swagger configuratie: ```php 'swagger' => [ 'securityDefinitions' => [ 'BearerAuth' => [ 'type' => 'apiKey', 'name' => 'Authorization', 'in' => 'header', 'description' => 'Bearer token authenticatie', ], ], 'security' => [ ['BearerAuth' => []] ], ]; ``` ## Annotaties in Controllers ### Basis Controller Annotatie ```php /** * @OA\Info( * title="Mijn API", * version="1.0.0", * description="API Documentatie voor Laravel applicatie" * ) * * @OA\Server( * url="http://localhost:8000/api/v1", * description="Lokale ontwikkelserver" * ) * * @OA\SecurityScheme( * securityScheme="BearerAuth", * type="apiKey", * in="header", * name="Authorization" * ) */ class ApiController extends Controller { // ... } ``` ### Route Annotatie Voorbeeld ```php /** * @OA\Get( * path="/api/v1/gebruikers", * summary="Lijst van gebruikers ophalen", * tags={"Gebruikers"}, * security={{"BearerAuth":{}}}, * @OA\Response( * response=200, * description="Succesvolle response", * @OA\JsonContent( * type="array", * @OA\Items(ref="#/components/schemas/Gebruiker") * ) * ), * @OA\Response( * response=401, * description="Niet geauthenticeerd" * ) * ) */ public function index() { return response()->json(User::all()); } ``` ## Schema Definities ### Model Annotatie ```php /** * @OA\Schema( * schema="Gebruiker", * type="object", * title="Gebruiker", * required={"id", "naam", "email"}, * @OA\Property( * property="id", * type="integer", * format="int64" * ), * @OA\Property( * property="naam", * type="string" * ), * @OA\Property( * property="email", * type="string", * format="email" * ) * ) */ class User extends Model { // ... } ``` ## Automatisering ### 1. Composer Scripts Voeg toe aan `composer.json`: ```json { "scripts": { "generate-docs": "php artisan l5-swagger:generate", "update-docs": "php artisan l5-swagger:generate --all" } } ``` ### 2. Git Hook (Optioneel) Maak `.git/hooks/post-commit`: ```bash #!/bin/bash php artisan l5-swagger:generate ``` ## Gebruik ### Documentatie Genereren ```bash # Eén keer genereren php artisan l5-swagger:generate # Alle versies genereren php artisan l5-swagger:generate --all # Via Composer composer run generate-docs ``` ### Documentatie Bekijken - JSON output: `/storage/api-docs/v1/api-docs.json` - Web interface: `/api/documentation` ## Extra Functionaliteiten ### 1. Environment-specifieke Configuratie ```php // In AppServiceProvider public function boot() { if (config('l5-swagger.documentations.v1.api.host') === null) { config(['l5-swagger.documentations.v1.api.host' => config('app.url')]); } } ``` ### 2. Automatische Regeneratie bij Wijzigingen Voeg toe aan `App\Console\Kernel`: ```php protected function schedule(Schedule $schedule) { $schedule->command('l5-swagger:generate')->daily(); } ``` Dit systeem zorgt voor: - Automatische JSON-documentatie gegenereerd vanuit code-annotaties - Versiebeheer (v1.0) zoals gevraagd - Authenticatie-headers in alle endpoints - Real-time updates na codewijzigingen - Professionele OpenAPI 3.0-compliant documentatie Start met het annoteren van je controllers en modellen, en run `php artisan l5-swagger:generate` om je documentatie te genereren!