Ontwerp een Geavanceerd Laravel API Versiebeheer en Documentatie Systeem
description
Met deze prompt kan de gebruiker een professioneel API-versiebeheer en documentatiesysteem opzetten dat de onderhoudbaarheid en schaalbaarheid van hun Laravel-project aanzienlijk verbetert. Het lost problemen op zoals het tegelijk ondersteunen van meerdere API-versies en het makkelijk bijhouden van wijzigingen. Deze aanpak is beter dan alternatieven omdat het automatisering combineert met duidelijke structuur en gebruiksvriendelijke documentatie.
prompt
Help mij een geavanceerd versiebeheer- en documentatiesysteem op te zetten voor mijn Laravel API. Ik wil dat het systeem automatisch versies beheert, oude versies ondersteunt en duidelijke API-documentatie genereert. Beschrijf hoe ik API-versies kan definiëren: <geef aan hoe je API-versies wilt ...
try_prompt
generate_helper
disclaimerOnPageApi
tags
ai_answers
provider: openai
model: gpt-4.1-nano
Natuurlijk! Hier is een uitgebreide gids voor het opzetten van een geavanceerd versiebeheer- en documentatiesysteem voor je Laravel API:
**1. API-versies definiëren in routes**
De meest gebruikelijke aanpak is om API-versies in de URL op te nemen, bijvoorbeeld `/api/v1/endpoint`. Dit doe je door je routes in `routes/api.php` te groeperen:
```php
use Illuminate\Support\Facades\Route;
// Versie 1 routes
Route::prefix('v1')->group(function () {
Route::get('/users', [UserController::class, 'index']);
// andere v1 endpoints
});
// Versie 2 routes
Route::prefix('v2')->group(function () {
Route::get('/users', [UserControllerV2::class, 'index']);
// andere v2 endpoints
});
```
**2. Controllers voor verschillende versies**
Voor elke versie maak je een aparte controller, bijvoorbeeld `UserController` voor v1 en `UserControllerV2` voor v2:
```php
namespace App\Http\Controllers\API\V1;
use App\Http\Controllers\Controller;
class UserController extends Controller
{
public function index()
{
// Response structuur voor v1
return response()->json([
'status' => 'success',
'data' => [
// gebruikersgegevens
]
]);
}
}
```
```php
namespace App\Http\Controllers\API\V2;
use App\Http\Controllers\Controller;
class UserControllerV2 extends Controller
{
public function index()
{
// Response structuur voor v2
return response()->json([
'success' => true,
'users' => [
// gebruikersgegevens
],
'meta' => [
'version' => 'v2'
]
]);
}
}
```
**3. Versiebeheer en ondersteuning voor oude versies**
Door aparte route-groepen en controllers te gebruiken, houd je verschillende versies actief. Je kunt oudere versies blijven onderhouden en aanpassen zonder dat ze de nieuwe versies beïnvloeden.
**4. Documentatie genereren met Swagger of Scribe**
**Gebruik van Scribe (aanbevolen voor Laravel):**
- Installeer Scribe via Composer:
```bash
composer require --dev knuckleswtf/scribe
```
- Publiceer de configuratie en views:
```bash
php artisan vendor:publish --provider="Knuckles\Scribe\ScribeServiceProvider"
```
- Voeg annotaties toe boven je API-methodes om de documentatie te verbeteren:
```php
/**
* @group Users
*
* Get list of users
*
* @response 200 {
* "status": "success",
* "data": [...]
* }
*/
public function index()
{
// ...
}
```
- Genereer documentatie met:
```bash
php artisan scribe:generate
```
De gegenereerde documentatie wordt in de `public/docs` directory geplaatst en is automatisch up-to-date bij elke nieuwe generatie.
**Gebruik van Swagger:**
- Installeer Swagger-UI en Swagger-PHP via Composer.
- Voeg annotaties toe in je controllers en models volgens OpenAPI-specificaties.
- Genereer een JSON of YAML specificatie en serveer deze via een route.
- Gebruik Swagger-UI om de API visueel te documenteren.
**5. Versiebeheer en wijzigingsbeheer in documentatie**
- Maak aparte secties of pagina’s voor elke API-versie.
- Documenteer de response-structuren en eventuele wijzigingen per versie.
- Gebruik bijvoorbeeld `@since` annotaties of aparte documentatiebestanden voor elke versie.
**6. Voorbeeld: API versiebeheer met gescheiden controllers en routes**
```php
// routes/api.php
Route::prefix('v1')->group(function () {
Route::get('/users', [App\Http\Controllers\API\V1\UserController::class, 'index']);
});
Route::prefix('v2')->group(function () {
Route::get('/users', [App\Http\Controllers\API\V2\UserControllerV2::class, 'index']);
});
```
**7. Extra tips**
- Overweeg het gebruik van API-parameters zoals `Accept` headers (`application/vnd.yourapp.v1+json`) voor versiebeheer, naast URL-versies.
- Gebruik een versie-beheerstrategie die past bij je team en projectvereisten.
- Documenteer alle endpoints, parameters en responses duidelijk en versieer je documentatie.
Met bovenstaande aanpak heb je een robuust systeem voor versiebeheer, automatische documentatie en onderhoud van oude versies, wat de schaalbaarheid en het gebruiksgemak van je Laravel API aanzienlijk verbetert.
provider: deepseek
model: deepseek-chat
Zeker, ik help je een geavanceerd versiebeheersysteem op te zetten voor je Laravel API. Hier is een complete handleiding:
## 1. Route Versiebeheer
### Route Definition
```php
// routes/api.php
Route::prefix('v1')->group(function () {
Route::get('/users', [App\Http\Controllers\Api\V1\UserController::class, 'index']);
Route::get('/users/{id}', [App\Http\Controllers\Api\V1\UserController::class, 'show']);
});
Route::prefix('v2')->group(function () {
Route::get('/users', [App\Http\Controllers\Api\V2\UserController::class, 'index']);
Route::get('/users/{id}', [App\Http\Controllers\Api\V2\UserController::class, 'show']);
});
```
### Conditionele Route Loading
```php
// App\Providers\RouteServiceProvider
public function boot()
{
$this->configureRateLimiting();
$this->routes(function () {
// Laad alleen actieve versies
if (config('api.versions.v1.active')) {
Route::prefix('api/v1')
->middleware('api')
->namespace('App\Http\Controllers\Api\V1')
->group(base_path('routes/api_v1.php'));
}
if (config('api.versions.v2.active')) {
Route::prefix('api/v2')
->middleware('api')
->namespace('App\Http\Controllers\Api\V2')
->group(base_path('routes/api_v2.php'));
}
});
}
```
## 2. Controller Structuur
### V1 Controller
```php
// app/Http/Controllers/Api/V1/UserController.php
namespace App\Http\Controllers\Api\V1;
use App\Http\Controllers\Controller;
use App\Models\User;
class UserController extends Controller
{
public function index()
{
$users = User::all();
return response()->json([
'success' => true,
'data' => $users->map(function ($user) {
return [
'id' => $user->id,
'name' => $user->name,
'email' => $user->email
];
})
]);
}
}
```
### V2 Controller (Verbeterde structuur)
```php
// app/Http/Controllers/Api/V2/UserController.php
namespace App\Http\Controllers\Api\V2;
use App\Http\Controllers\Controller;
use App\Models\User;
use App\Http\Resources\V2\UserResource;
class UserController extends Controller
{
public function index()
{
$users = User::with('profile')->get();
return response()->json([
'version' => 'v2',
'timestamp' => now()->toISOString(),
'data' => UserResource::collection($users),
'pagination' => [
'total' => $users->count(),
'per_page' => 15
]
]);
}
}
```
## 3. API Resource Classes
```php
// app/Http/Resources/V2/UserResource.php
namespace App\Http\Resources\V2;
use Illuminate\Http\Resources\Json\JsonResource;
class UserResource extends JsonResource
{
public function toArray($request)
{
return [
'id' => $this->id,
'full_name' => $this->name,
'email_address' => $this->email,
'profile' => [
'avatar' => $this->profile->avatar_url,
'bio' => $this->profile->bio
],
'created_at' => $this->created_at->toISOString(),
'updated_at' => $this->updated_at->toISOString()
];
}
}
```
## 4. Swagger/OpenAPI Documentatie
### Installatie
```bash
composer require darkaonline/l5-swagger
php artisan vendor:publish --provider "L5Swagger\L5SwaggerServiceProvider"
```
### API Annotaties
```php
/**
* @OA\Info(
* title="Mijn API",
* version="1.0.0",
* description="API Documentatie voor versie 1"
* )
*
* @OA\Server(
* url="http://localhost:8000/api/v1",
* description="API Server v1"
* )
*
* @OA\Server(
* url="http://localhost:8000/api/v2",
* description="API Server v2"
* )
*/
/**
* @OA\Get(
* path="/users",
* summary="Lijst van gebruikers",
* tags={"Users"},
* @OA\Response(
* response=200,
* description="Success",
* @OA\JsonContent(
* type="object",
* @OA\Property(property="success", type="boolean"),
* @OA\Property(
* property="data",
* type="array",
* @OA\Items(ref="#/components/schemas/User")
* )
* )
* )
* )
*/
```
## 5. Configuratie Bestanden
### API Versie Config
```php
// config/api.php
return [
'versions' => [
'v1' => [
'active' => true,
'deprecated' => false,
'support_until' => '2024-12-31'
],
'v2' => [
'active' => true,
'deprecated' => false,
'support_until' => '2025-12-31'
]
],
'default_version' => 'v2'
];
```
### Middleware voor Versie Handling
```php
// app/Http/Middleware/APIVersion.php
namespace App\Http\Middleware;
use Closure;
use Illuminate\Http\Request;
class APIVersion
{
public function handle(Request $request, Closure $next, $guard)
{
config(['app.api_version' => $guard]);
return $next($request);
}
}
```
## 6. Change Log Bijhouden
```php
// app/Services/APIVersionService.php
namespace App\Services;
class APIVersionService
{
protected $changes = [
'v2' => [
'users' => [
'added' => ['profile data', 'pagination'],
'removed' => ['success field'],
'changed' => ['email -> email_address']
]
]
];
public function getChanges($version)
{
return $this->changes[$version] ?? [];
}
public function logChange($version, $endpoint, $changeType, $description)
{
// Log wijzigingen in database of bestand
}
}
```
## 7. Automatische Documentatie Generatie
### Scribe Configuratie
```bash
composer require knuckleswtf/scribe
php artisan vendor:publish --tag=scribe-config
```
### Scribe Annotaties
```php
/**
* @group Gebruikersbeheer v2
*
* Haal een lijst van gebruikers op met uitgebreide informatie
*
* @responseField data array Lijst van gebruikers
* @responseField pagination object Paginatie informatie
* @responseField version string API versie
*/
```
## 8. Deprecation Headers
```php
// app/Http/Middleware/DeprecationWarning.php
public function handle($request, Closure $next)
{
$response = $next($request);
if (str_contains($request->path(), 'api/v1')) {
$response->header('Deprecation', 'true');
$response->header('Sunset', 'Wed, 31 Dec 2024 23:59:59 GMT');
$response->header('Link', '<http://localhost:8000/api/v2/users>; rel="successor-version"');
}
return $response;
}
```
## 9. Testen en Validatie
```php
// tests/Feature/ApiVersionTest.php
public function test_both_versions_active()
{
// Test v1
$responseV1 = $this->get('/api/v1/users');
$responseV1->assertStatus(200);
// Test v2
$responseV2 = $this->get('/api/v2/users');
$responseV2->assertStatus(200);
// Verify different structures
$this->assertArrayHasKey('success', $responseV1->json());
$this->assertArrayHasKey('version', $responseV2->json());
}
```
Dit systeem biedt:
- Duidelijk versiebeheer via route prefixes
- Automatische documentatie generatie
- Ondersteuning voor multiple actieve versies
- Duidelijke changelog tracking
- Deprecation warnings voor oude versies
- Gestructureerde response formaten per versie
Je kunt de documentatie bekijken via `/api/documentation` (Swagger) of `/docs` (Scribe) na configuratie.