Ontwikkel een Geavanceerde Laravel API Documentatie met OpenAPI Spec
description
Met deze prompt ontwikkel je een professionele en automatische API-documentatie die je Laravel backend duidelijk en onderhoudbaar maakt. Je voorkomt miscommunicatie met frontend-ontwikkelaars en externe gebruikers en bespaart tijd door documentatie automatisch te genereren en up-to-date te houden. Deze aanpak verbetert de kwaliteit van je API en verhoogt de efficiëntie bij verdere ontwikkeling.
prompt
Help me een uitgebreide en gestructureerde API-documentatie te maken voor mijn Laravel backend met behulp van OpenAPI Specificatie. Mijn API functionaliteiten omvatten: <beschrijf de belangrijkste API-eindpunten en hun doelen>. Ik wil dat de documentatie ...
try_prompt
generate_helper
disclaimerOnPageApi
tags
ai_answers
provider: openai
model: gpt-4.1-nano
Zeker! Hieronder vind je een uitgebreide en gestructureerde uitleg over het integreren van OpenAPI specificaties in je Laravel backend, inclusief voorbeelden en tips voor automatische generatie en onderhoud.
---
# 1. Introductie
De OpenAPI Specificatie (voorheen Swagger) stelt je in staat om je API te documenteren op een gestructureerde en machineleesbare manier. Dit maakt automatische documentatie, validatie en testing makkelijker.
---
# 2. Integratie van OpenAPI in Laravel
## a. Keuze van tools
Voor Laravel zijn er verschillende pakketten die OpenAPI specificaties ondersteunen:
- **Laravel OpenAPI Generator** (bijvoorbeeld [Nuno Maduro's Laravel OpenAPI](https://github.com/Neklo/laravel-openapi))
- **Swagger-PHP** (https://github.com/swagger-api/swagger-php) — het meest gebruikte PHP-pakket om OpenAPI specificaties te schrijven in commentaarblokken.
Voor automatische generatie en onderhoud is `swagger-php` zeer geschikt.
## b. Installatie van swagger-php
Gebruik Composer:
```bash
composer require zircote/swagger-php
```
## c. Annotaties toevoegen
Je documenteert je API met PHP-annotaties direct in je controllers of aparte YAML/JSON bestanden.
---
# 3. Voorbeeld van API-documentatie met swagger-php
Hieronder een voorbeeld van hoe je je API kunt documenteren met annotations:
### a. Documentatie voor GET /producten
```php
/**
* @OA\Get(
* path="/producten",
* summary="Lijst producten ophalen",
* tags={"Producten"},
* @OA\Response(
* response=200,
* description="Een lijst van producten",
* @OA\JsonContent(
* type="array",
* @OA\Items(
* @OA\Property(property="id", type="integer"),
* @OA\Property(property="naam", type="string"),
* @OA\Property(property="prijs", type="number", format="float")
* )
* )
* )
* )
*/
public function index()
{
// ...
}
```
### b. Documentatie voor POST /bestellingen
```php
/**
* @OA\Post(
* path="/bestellingen",
* summary="Nieuwe bestelling plaatsen",
* tags={"Bestellingen"},
* @OA\RequestBody(
* required=true,
* @OA\JsonContent(
* required={"klant_id","producten"},
* @OA\Property(property="klant_id", type="integer"),
* @OA\Property(
* property="producten",
* type="array",
* @OA\Items(
* @OA\Property(property="product_id", type="integer"),
* @OA\Property(property="aantal", type="integer")
* )
* )
* )
* ),
* @OA\Response(
* response=201,
* description="Bestelling succesvol geplaatst",
* @OA\JsonContent(
* @OA\Property(property="bestelling_id", type="integer"),
* @OA\Property(property="status", type="string")
* )
* ),
* @OA\Response(
* response=400,
* description="Fout bij aanvraag",
* @OA\JsonContent(
* @OA\Property(property="error", type="string")
* )
* )
* )
*/
public function store(Request $request)
{
// ...
}
```
### c. Documentatie voor PUT /gebruikers/{id}
```php
/**
* @OA\Put(
* path="/gebruikers/{id}",
* summary="Gebruikersgegevens bijwerken",
* tags={"Gebruikers"},
* @OA\Parameter(
* name="id",
* in="path",
* description="ID van de gebruiker",
* required=true,
* @OA\Schema(type="integer")
* ),
* @OA\RequestBody(
* required=true,
* @OA\JsonContent(
* @OA\Property(property="naam", type="string"),
* @OA\Property(property="email", type="string", format="email")
* )
* ),
* @OA\Response(
* response=200,
* description="Gebruiker bijgewerkt",
* @OA\JsonContent(
* @OA\Property(property="id", type="integer"),
* @OA\Property(property="naam", type="string"),
* @OA\Property(property="email", type="string")
* )
* ),
* @OA\Response(
* response=404,
* description="Gebruiker niet gevonden",
* @OA\JsonContent(
* @OA\Property(property="error", type="string")
* )
* )
* )
*/
public function update($id, Request $request)
{
// ...
}
```
---
# 4. Automatisch genereren van de OpenAPI-documentatie
Gebruik een commando zoals:
```bash
php artisan swagger-lume:generate
```
of, afhankelijk van de tool, bijvoorbeeld:
```bash
vendor/bin/swagger app/Http/Controllers --output public/swagger.yaml
```
Zo blijft je documentatie up-to-date met je code.
---
# 5. Documentatie van authenticatie en foutafhandeling
## a. Authenticatie
Voeg bijvoorbeeld een Bearer Token toe in de header:
```php
/**
* @OA\SecurityScheme(
* securityScheme="bearerAuth",
* type="http",
* scheme="bearer",
* bearerFormat="JWT"
* )
*/
```
En gebruik `security` in je endpoints:
```php
/**
* @OA\Get(
* path="/producten",
* security={{"bearerAuth":{}}},
* ...
* )
*/
```
## b. Foutafhandeling
Documenteer verschillende fout responses zoals 400, 404, 500, etc., zoals in de voorbeelden hierboven.
---
# 6. Onderhoud en best practices
- Plaats alle annotaties dicht bij je controller methodes.
- Gebruik consistente tags en responseformaten.
- Automatiseer de generatie met CI/CD pipelines.
- Bewaar je OpenAPI specificatie in een aparte YAML/JSON file voor versiebeheer.
---
# Samenvatting
- Installeer `swagger-php`.
- Voeg annotaties toe aan je controllers voor elke API-endpoint.
- Genereer automatisch de OpenAPI specificatie.
- Documenteer authenticatie en foutafhandeling expliciet.
- Houd je documentatie synchroon met je code voor makkelijk onderhoud.
---
Heeft je verdere hulp nodig bij een specifiek onderdeel of voorbeeld?
provider: deepseek
model: deepseek-chat
Zeker! Ik leg je stap voor stap uit hoe je OpenAPI-documentatie implementeert in Laravel.
## 1. Package Installatie
Installeer de `darkaonline/l5-swagger` package:
```bash
composer require darkaonline/l5-swagger
php artisan vendor:publish --provider="L5Swagger\L5SwaggerServiceProvider"
```
## 2. Configuratie
In `config/l5-swagger.php`:
```php
return [
'default' => 'default',
'documentations' => [
'default' => [
'api' => [
'title' => 'Mijn API Documentatie',
'version' => '1.0.0',
],
],
],
'paths' => [
'docs' => storage_path('api-docs'),
'docs_json' => 'api-docs.json',
'annotations' => base_path('app'),
],
];
```
## 3. Annotaties toevoegen aan controllers
### ProductController.php - GET /producten
```php
/**
* @OA\Get(
* path="/producten",
* summary="Lijst van alle producten",
* tags={"Producten"},
* @OA\Response(
* response=200,
* description="Succesvolle response",
* @OA\JsonContent(
* type="array",
* @OA\Items(ref="#/components/schemas/Product")
* )
* ),
* @OA\Response(
* response=401,
* description="Niet geauthenticeerd"
* )
* )
*/
public function index()
{
return Product::all();
}
```
### BestellingController.php - POST /bestellingen
```php
/**
* @OA\Post(
* path="/bestellingen",
* summary="Nieuwe bestelling plaatsen",
* tags={"Bestellingen"},
* security={{"bearerAuth":{}}},
* @OA\RequestBody(
* required=true,
* @OA\JsonContent(
* required={"gebruiker_id","producten"},
* @OA\Property(property="gebruiker_id", type="integer", example=1),
* @OA\Property(
* property="producten",
* type="array",
* @OA\Items(
* type="object",
* required={"product_id", "aantal"},
* @OA\Property(property="product_id", type="integer", example=5),
* @OA\Property(property="aantal", type="integer", example=2)
* )
* ),
* @OA\Property(property="opmerking", type="string", example="Lever aan de achterdeur")
* )
* ),
* @OA\Response(
* response=201,
* description="Bestelling succesvol aangemaakt",
* @OA\JsonContent(ref="#/components/schemas/Bestelling")
* ),
* @OA\Response(
* response=422,
* description="Validatiefouten",
* @OA\JsonContent(
* @OA\Property(property="message", type="string", example="De opgegeven data was ongeldig."),
* @OA\Property(
* property="errors",
* type="object",
* @OA\Property(
* property="gebruiker_id",
* type="array",
* @OA\Items(type="string", example="Het gebruiker_id veld is verplicht.")
* )
* )
* )
* ),
* @OA\Response(
* response=401,
* description="Niet geauthenticeerd"
* )
* )
*/
public function store(Request $request)
{
// Je bestellingslogica hier
}
```
### GebruikerController.php - PUT /gebruikers/{id}
```php
/**
* @OA\Put(
* path="/gebruikers/{id}",
* summary="Gebruikersgegevens bijwerken",
* tags={"Gebruikers"},
* security={{"bearerAuth":{}}},
* @OA\Parameter(
* name="id",
* in="path",
* required=true,
* @OA\Schema(type="integer")
* ),
* @OA\RequestBody(
* required=true,
* @OA\JsonContent(ref="#/components/schemas/GebruikerUpdate")
* ),
* @OA\Response(
* response=200,
* description="Gebruiker succesvol bijgewerkt",
* @OA\JsonContent(ref="#/components/schemas/Gebruiker")
* ),
* @OA\Response(
* response=404,
* description="Gebruiker niet gevonden"
* )
* )
*/
public function update(Request $request, $id)
{
// Je updatelogica hier
}
```
## 4. Schema definities
Voeg schema's toe in je controllers of in aparte files:
```php
/**
* @OA\Schema(
* schema="Product",
* type="object",
* @OA\Property(property="id", type="integer", example=1),
* @OA\Property(property="naam", type="string", example="Stoel"),
* @OA\Property(property="prijs", type="number", format="float", example=49.99),
* @OA\Property(property="voorraad", type="integer", example=25)
* )
*/
/**
* @OA\Schema(
* schema="Bestelling",
* type="object",
* @OA\Property(property="id", type="integer", example=1),
* @OA\Property(property="gebruiker_id", type="integer", example=1),
* @OA\Property(property="totaalbedrag", type="number", format="float", example=99.98),
* @OA\Property(property="status", type="string", example="verwerkt"),
* @OA\Property(property="aangemaakt_op", type="string", format="date-time")
* )
*/
/**
* @OA\Schema(
* schema="GebruikerUpdate",
* type="object",
* @OA\Property(property="naam", type="string", example="Jan Jansen"),
* @OA\Property(property="email", type="string", format="email", example="jan@voorbeeld.nl"),
* @OA\Property(property="telefoon", type="string", example="0612345678")
* )
*/
```
## 5. Authenticatie documenteren
Voeg deze component toe in je configuratie:
```php
/**
* @OA\SecurityScheme(
* securityScheme="bearerAuth",
* type="http",
* scheme="bearer",
* bearerFormat="JWT"
* )
*/
```
## 6. Foutafhandeling documenteren
Maak een globale error handler:
```php
/**
* @OA\Schema(
* schema="Error",
* type="object",
* @OA\Property(property="message", type="string"),
* @OA\Property(property="errors", type="object", nullable=true)
* )
*/
/**
* @OA\Response(
* response="Unauthorized",
* description="Niet geauthenticeerd",
* @OA\JsonContent(
* @OA\Property(property="message", type="string", example="Unauthenticated.")
* )
* )
*/
```
## 7. Documentatie genereren en bekijken
```bash
# Documentatie genereren
php artisan l5-swagger:generate
# Documentatie bekijken (ga naar)
http://jouw-domein.nl/api/documentation
```
## 8. Onderhoud tips
- Gebruik PHPStorm of VSCode met OpenAPI extensies voor autocomplete
- Houd schema's consistent door hergebruik met `$ref`
- Gebruik tags om endpoints te groeperen
- Documenteer wijzigingen in de versie history
## 9. CI/CD integratie
Voeg toe aan je `.gitlab-ci.yml` of GitHub Actions:
```yaml
generate-docs:
script:
- composer install
- php artisan l5-swagger:generate
artifacts:
paths:
- storage/api-docs/
```
De documentatie wordt nu automatisch gegenereerd bij elke wijziging en is altijd up-to-date met je codebase!