Schémas YAML & JSON

Décrivez toute votre API dans un fichier déclaratif et versionnable : committez-le, relisez-le en PR, régénérez à volonté.

Schéma YAML

Créez api-schema.yaml à la racine du projet :

options:
  query_builder: true
  pest: true

entities:
  Category:
    fields:
      name: string unique
    relations:
      posts: hasMany Post

  Post:
    soft_deletes: true
    fields:
      title: string
      content: text nullable
      status: enum(draft,published) default=draft
      views: { type: integer, default: 0 }
    relations:
      tags: belongsToMany Tag

  Tag:
    fields:
      name: string unique

php artisan make:fullapi --schema=api-schema.yaml

Quand api-schema.yaml (ou .yml / .json) existe à la racine du projet, le flag devient même optionnel : un simple php artisan make:fullapi le détecte automatiquement.

Syntaxe des champs

Les champs acceptent un raccourci (title: string) ou un mapping complet quand il faut des clés supplémentaires comme rules :

fields:
  title: string
  slug: string unique
  excerpt: text nullable
  code: string primary
  status: enum(draft,published) default=draft
  views: { type: integer, default: 0, rules: 'min:0' }

unique, nullable et default= décorent le raccourci, et primary promeut le champ en clé primaire personnalisée.

Options

Les options peuvent être globales (sous options:) ou par entité :

Option	Effet
soft_deletes: true	Trait SoftDeletes + endpoints restore/force-delete
query_builder: true	Filtrage & tri Spatie QueryBuilder sur l'index
pest: true	Tests Pest au lieu de PHPUnit
json_api: true	Resources JSON:API (Laravel 12.45+, resources classiques sur les versions antérieures)

Autocomplétion dans l'éditeur

Le package fournit un JSON Schema de ce format. Faites-y pointer la première ligne du fichier, et tout éditeur qui fait tourner le serveur de langage YAML complète les clés et les types, et signale les fautes de frappe comme strng ou nulable avant la génération :

# yaml-language-server: $schema=https://nameless0l.github.io/laravel-api-generator/schema/api-schema.json

L'extension VS Code applique d'elle-même le schéma à api-schema.yaml, api-schema.yml et api-schema.json. Hors ligne, le même fichier se trouve dans vendor/nameless/laravel-api-generator/resources/schema/api-schema.json.

Hors de l'éditeur, make:fullapi génère quand même un champ de type inconnu comme une colonne string, et le signale par un avertissement unknown_field_type qui nomme le champ.

Ce que vous obtenez gratuitement

• Relations inverses synthétisées : déclarez posts: hasMany Post sur Category, et Post reçoit le belongsTo et sa colonne de migration category_id. Détails.
• Ordre sûr pour les clés étrangères : les entités sont générées parents d'abord, php artisan migrate ne trébuche jamais sur une table manquante.
• Pivots automatiques : chaque belongsToMany crée sa migration pivot.

Mode JSON en masse (class_data.json)

Le format historique de génération en masse, toujours pleinement supporté : créez class_data.json à la racine du projet et lancez php artisan make:fullapi sans argument. Voir Relations → Mode JSON pour le format, ou téléchargez le schéma Blog d'exemple.

Compatible IA

Un fichier YAML unique décrivant toute une API est une cible idéale pour un assistant IA : demandez un schéma à votre modèle préféré, relisez-le, générez. L'assistant ne peut pas halluciner de chemins de fichiers, puisque c'est le générateur qui décide de l'arborescence. Avec Laravel Boost, l'agent apprend ce format grâce au skill du package : voir Outils et agents.