Petite question, qu’est-ce qui est pire qu’écrire des tests pour un développeur ?
Écrire la documentation !
Lorsque l’on développe une AI, on doit souvent écrire un Swagger, OpenAPI ou autre. À cela plusieurs solutions: le faire à la main, demander à son bon vieux GitHub Copilot de le faire ou bien ne pas le faire.
Et si je vous disais qu’un package pouvait lire vos validateurs Laravel et créer une documentation en ligne.
Je vous présente Scramble ! Créer en quelques minutes une documentation en ligne de votre API simplement.
C’est automatique, c’est magique !
Quand on y pense, notre code possède toutes les informations nécessaires! Des règles de validations, des paramètres en query, dans l’URL et dans les toutes les méthodes appeler sur notre $request.
Quand vous utiliser les model bindings dans votre route, Scramble va automatiquement regarder le type de l’id. Si vous avez un id incrémental, on verra un type integer et si vous utilisez un UUID, on aura un type string avec le format de l’UUID.
OK, mais s’il fait une erreur?
En plus de vous générer une structure et les paramètres, vous pouvez ajouter des descriptions, des exemples et des valeurs par défaut.
Grâce aux attributs, on peut changer les oublis ou les erreurs de Scramble:
#[BodyParameter('name', 'The name of the company')]
public function store(Request $request)
{
$request->validate([
'name' => ['required', 'string'],
]);
...
}Si vous êtes allergique aux attributs, vous pouvez aussi utiliser la PHPDOC:
public function store(Request $request){
$request->validate([
// The name of the company.
'name' => ['required', 'string'],
]);
...
}Évidemment, il existe des attributs pour les paramètres de chemin (#[PathParameter]) ou en query (#[QueryParameter]) et pour les éventuels cookies (#[CookieParameter]) ou headers (#[HeaderParameter]).
Vous allez me dire: “Trop bien! Mais maintenant mon Product Owner veut écrire un roman pour chaque appel”.
S’il veut donner un petit nom et écrire une description, il peut - grâce à la PHPDOC !
Vous ne passerez pas !
Normalement, votre est API est protégé par un système d’authentification. Ici aussi, Scramble a tout prévu. Depuis votre ServiceProvider (je vous conseille d’en créer un juste pour la documentation), vous pouvez définir le type de sécurité mise en place.
public function boot(){
Scramble::configure()
->withDocumentTransformers(function (OpenApi $openApi) {
$openApi->secure(
SecurityScheme::http('bearer')
);
});
}Ici, on indique à Scramble que l’on utilise des bearer token
Vous avez une route qui est quand même publique? Pas de problème !
/**
* @unauthenticated
*/
public function store(Request $request){
...
}Generate to impress 💅
Pour finir, si vous voulez grouper des routes et trier ces groupes, vous pouvez toujours avec l’attribut #[Group('Companies API)].
#[Group('Companies API')]
class CompaniesController {...}
#[Group('Domains API', weight: 2)]
class DomainsController {...}
Le meilleur pour la fin ?!
Votre développeur frontend ne veut pas toucher/voir au backend. Pas de soucis, vous pouvez exporter la documentation en JSON au format OPEN API 3.1.0 !
Vous utilisez Laravel Data ou Laravel Query Builder, j’ai une bonne et une mauvaise nouvelle pour vous !
Scramble le gère, mais dans ça version professionnelle. Pour 99$, vous pouvez générer automatiquement vos documentations pour TOUS vos projets.
Et cerise sur le gâteau. Scramble prévoit un SDK qui générera les types en temps réel pour vos projets en TypeScript.
Sources
- Roman Lytvynenko - In-depth guide on documenting API requests with Scramble