Proje: OkulUp API · Hub: OkulUp API — Conventions

OkulUp API — OpenAPI Dokümantasyon Pattern

Araç

L5 Swagger (darkaonline/l5-swagger) + PHP 8 attributes kullanılır.

Commit Öncesi Zorunlu Komut

php artisan l5-swagger:generate

Oluşan storage/api-docs/api-docs.json her commit’e dahil edilmeli.

Controller Attribute Pattern

#[OA\Get(
    path: '/api/meal-menus',
    summary: 'List meal menus',
    security: [['sanctum' => []]],
    tags: ['Meal Menus'],
    parameters: [
        new OA\Parameter(name: 'date', in: 'query', schema: new OA\Schema(type: 'string', format: 'date')),
    ],
    responses: [
        new OA\Response(response: 200, description: 'Meal menu list'),
        new OA\Response(response: 401, description: 'Unauthenticated'),
        new OA\Response(response: 403, description: 'Feature disabled'),
    ]
)]
public function index(Request $request): AnonymousResourceCollection

Schema Pattern (Resource’lar için)

#[OA\Schema(
    schema: 'UserResource',
    properties: [
        new OA\Property(property: 'id', type: 'integer'),
        new OA\Property(property: 'name', type: 'string'),
    ]
)]
class UserResource extends JsonResource

Güvenlik

• Public endpoint: security: []
• Auth gerektiren: security: [['sanctum' => []]]

Related

• api-kod-konvansiyonlari — controller patterns