okulcom-api — Swagger/OpenAPI Dokümantasyon Yapısı

Proje: Okul Platform · Hub: Okul Platform — Conventions

Swagger Altyapısı

darkaonline/l5-swagger — DarkaOnline L5 Swagger paketi. app/Swagger/ dizininde tüm Swagger tanımları.

Swagger Dizin Yapısı

app/Swagger/
├── Admin/        — Admin endpoint tanımları
├── Customer/     — Customer endpoint tanımları
├── General/      — General endpoint tanımları
├── Models/       — Model şemaları
├── Requests/     — Request şemaları
├── Resources/    — Resource şemaları
└── Responses/    — Standart response'lar

Standart Response Tipleri

SWR\OkResponse           → 200 OK
SWR\CreateResponse       → 201 Created
SWR\NoContentResponse    → 204 No Content
SWR\BadRequestResponse   → 400 Bad Request
SWR\UnauthorizedResponse → 401 Unauthorized
SWR\ForbiddenResponse    → 403 Forbidden
SWR\NotFoundResponse     → 404 Not Found
SWR\UnprocessableEntityResponse → 422 Unprocessable
SWR\FailResponse         → Genel hata
SWR\PaginatedResponse    → Sayfalanmış liste
SWR\SuccessResponse      → Genel başarı

Controller Kullanımı

use App\Swagger\Responses as SWR;
 
#[OA\Get(
    path: '/admin/schools',
    tags: ['Schools'],
    responses: [
        new SWR\PaginatedResponse(ref: '#/components/schemas/SchoolResource'),
        new SWR\UnauthorizedResponse(),
        new SWR\ForbiddenResponse(),
    ],
)]
#[OA\Parameter(name: 'filter[school_id]', in: 'query')]

OpenAPI Attribute’ları

PHP 8.1+ native attribute’ları kullanılıyor (annotation yerine):

• #[OA\Get(...)], #[OA\Post(...)], #[OA\Put(...)], #[OA\Delete(...)]
• #[OA\Parameter(...)]
• #[OA\RequestBody(...)]

PHPStan Swagger Exclusion

phpstan.neon.dist: app/Swagger/* coverage’dan hariç.

Related

• api-tech-stack — darkaonline/l5-swagger paketi
• api-response-structure — JsonResponse sınıfı