Swagger / OpenAPI¶

La documentation API de Primatch est générée via L5-Swagger (OpenAPI 3.0) à partir d'annotations PHP dans les controllers.

Accéder à la documentation¶

Environnement	URL
Développement	http://localhost:8010/api/documentation
Production	Sécurisé derrière authentification

Régénérer la documentation¶

make swagger-generate
# ou : docker exec -it primatch-api php artisan l5-swagger:generate

Toujours regénérer après modification

Après avoir ajouté ou modifié un endpoint, regénérer la documentation avant de committer.

Annoter un Controller¶

<?php

namespace App\Http\Controllers\Api\V1;

use OpenApi\Attributes as OA;

#[OA\Tag(name: 'Games', description: 'Gestion des parties de padel')]
class GameController extends Controller
{
    #[OA\Get(
        path: '/api/v1/games',
        summary: 'Lister les parties de l\'utilisateur connecté',
        security: [['bearerAuth' => []]],
        tags: ['Games'],
        responses: [
            new OA\Response(
                response: 200,
                description: 'Liste des matchs',
                content: new OA\JsonContent(
                    type: 'array',
                    items: new OA\Items(ref: '#/components/schemas/GameResource')
                )
            ),
            new OA\Response(response: 401, description: 'Non authentifié')
        ]
    )]
    public function index(): JsonResponse
    {
        // ...
    }

    #[OA\Post(
        path: '/api/v1/games',
        summary: 'Créer une nouvelle partie',
        security: [['bearerAuth' => []]],
        tags: ['Games'],
        requestBody: new OA\RequestBody(
            required: true,
            content: new OA\JsonContent(ref: '#/components/schemas/CreateGameRequest')
        ),
        responses: [
            new OA\Response(response: 201, description: 'Partie créée'),
            new OA\Response(response: 422, description: 'Erreur de validation')
        )]
    public function store(CreateGameRequest $request): JsonResponse
    {
        // ...
    }
}

Schemas (Models)¶

#[OA\Schema(
    schema: 'GameResource',
    properties: [
        new OA\Property(property: 'id', type: 'integer', example: 1),
        new OA\Property(property: 'type', type: 'string', enum: ['friendly', 'competitive']),
        new OA\Property(property: 'status', type: 'string', enum: ['open', 'full', 'in_progress', 'finished', 'score_validated', 'cancelled']),
        new OA\Property(property: 'scheduled_at', type: 'string', format: 'date-time'),
    ]
)]
class GameResource extends JsonResource { }