APICom

Generate TypeScript models, fetch services and React Query v5 hooks from local OpenAPI 3.0 JSON. Generated files are previewed before writing and existing files are protected.

Installation et utilisation

1. Installer apicom-1.0.0.vsix dans VS Code : Extensions → … → Installer à partir de VSIX.
2. Ouvrir le dossier du front-end.
3. Lancer APICom: Generate from OpenAPI JSON dans la palette.
4. Sélectionner le fichier OpenAPI JSON (un exemple est fourni dans les sources).
5. Choisir le dossier de sortie, par défaut src/api/generated.
6. Examiner l’aperçu puis confirmer la création.

APICom génère :

• types/api.types.ts : modèles et entrées/réponses des opérations.
• services/api.service.ts : services HTTP typés.
• services/client.ts : client fetch configurable, erreurs HTTP et annulation.
• hooks/use-api.ts : hooks useQuery pour GET et useMutation pour les autres méthodes.

Configurer le client généré une fois dans votre application :

import { configureApi } from './api/generated/services/client';
configureApi({ baseUrl: 'https://api.example.com' });

Installer React Query v5 dans l’application et fournir QueryClientProvider. Exemple d’utilisation :

const products = use_listProducts({ query: { page: 1 } });
const create = use_createProduct();
create.mutate({ body: { name: 'Produit' } });

Les noms dépendent de operationId. Les hooks utilisent le préfixe use_. Le signal d’annulation est transmis aux requêtes GET. Les clés de cache comprennent le nom de l’opération et son entrée. Les mutations n’invalident pas automatiquement d’autres requêtes : ces règles métier vous appartiennent.

Client existant

Configurer apicom.httpClientImport, par exemple @/api/client. Ce module doit exporter request<T>(path, options): Promise<T> et le type RequestOptions conformes au client généré. Un client Axios standard n’est pas directement compatible : écrire un adaptateur. APICom n’écrase et ne modifie aucun client existant.

Prise en charge

OpenAPI 3.0.x JSON, schémas locaux, types primitifs, objets, tableaux, enum, nullable, oneOf/anyOf/allOf, paramètres path/query/header simples, corps JSON, réponses JSON et réponses sans corps. Références locales de paramètres, requestBodies et responses à un niveau.

Non pris en charge : YAML, import URL, OpenAPI 3.1, Swagger 2, références externes, multipart/upload, cookies, objets dans les paramètres, styles de sérialisation complexes et références de path items. Ces cas doivent être adaptés avant génération ; les principaux cas non pris en charge provoquent une erreur explicite. Les contraintes de schéma ne deviennent pas des validations d’exécution. Les réponses non-JSON à l’exécution ne sont pas validées contre le type TypeScript.

Les métadonnées servers ne configurent pas automatiquement la base URL. Authentification, renouvellement de jetons, cookies et règles d’invalidation doivent être intégrés à votre application. Le client fetch fourni peut utiliser des en-têtes par défaut ; pour une authentification dynamique, utilisez un adaptateur adapté.

L’extension fonctionne localement ou dans l’hôte distant de VS Code. Aucun service externe, télémétrie ni requête réseau. Le fichier source est limité à 10 Mo. Les spécifications peuvent contenir des informations sensibles : l’aperçu reste dans VS Code.

Développement

Node.js 20+. npm test, npm run check, npm run package. F5 dans VS Code ouvre un hôte de développement. Aucun module npm requis à l’exécution de l’extension. React Query est requis dans l’application destinataire.

Test manuel : générer depuis examples/openapi.json, examiner les 4 fichiers, essayer une seconde génération dans le même dossier (elle doit refuser l’écrasement), configurer la base URL et compiler le code dans votre application React Query v5.

Publication

Publisher : infinityinnovationsdev. Nom technique : apicom. Version : 1.0.0. Envoyer le VSIX dans New extension → Visual Studio Code sur le Marketplace. La disponibilité du nom reste à confirmer lors de l’envoi. Aucun dépôt GitHub n’est inventé : ajoutez repository/homepage/bugs après création du vrai dépôt.

MIT — Infinity Innovations.