Importer une API OpenAPI

Une spec OpenAPI décrit votre API ; Voozeo en tire un outil par opération. Cette page explique comment l'importer et la tenir à jour.

Formats acceptés

• Versions : OpenAPI 3.0.x et 3.1.x. Swagger 2.0 est refusé (UNSUPPORTED_SPEC_VERSION) : convertissez-le d'abord en OpenAPI 3.
• Formats : JSON ou YAML, fichiers .json, .yaml ou .yml.
• Taille : 5 Mo maximum, que ce soit un fichier ou une URL.

Importer un fichier

1. Ouvrez l'onglet « Sources » du serveur et cliquez sur « Importer une spec OpenAPI ».
2. Choisissez la méthode « Fichier » et sélectionnez votre fichier.
3. Cliquez sur « Importer ».

Un message indique le nombre d'outils générés, avec un lien « Voir les outils ».

Importer depuis une URL

Choisissez la méthode « URL » et saisissez l'adresse HTTPS publique de la spec. Voozeo la télécharge : le téléchargement est limité à 10 secondes, et une réponse autre que 2xx donne UPSTREAM_FETCH_FAILED. Les adresses privées ou internes sont refusées (UNSAFE_URL). Si votre spec n'est pas publique, importez-la plutôt comme fichier.

L'ensemble de l'import doit se terminer en 28 secondes, sinon il échoue avec INGESTION_TIMEOUT.

Références ($ref)

Seules les références locales (#/components/schemas/Order) sont suivies. Voozeo les remplace par leur contenu, avec ces garde-fous :

• une imbrication au-delà de 10 niveaux est remplacée par un schéma vide ;
• une référence circulaire est remplacée par un schéma vide ;
• une référence vers un fichier ou une URL externe est ignorée (schéma vide).

Chacun de ces cas produit un avertissement (voir Avertissements).

Une seule source par serveur

Un serveur ne porte qu'une spec OpenAPI. Un nouvel import remplace l'ancien : c'est le principe de la mise à jour.

Mettre à jour la spec

Importez simplement la nouvelle version. Vos personnalisations (activation, nom, description des outils) sont conservées pour les opérations qui existent toujours : Voozeo les reconnaît par leur operationId ou, à défaut, par la méthode et le chemin. Renommer un operationId dans la spec fait donc apparaître un nouvel outil. Une URL de base saisie par vos soins dans l'onglet « API cible » n'est jamais écrasée. Sinon, l'URL de base est la première entrée de servers de la spec (variables remplacées par leur valeur par défaut) ; elle doit être en HTTPS, sinon elle est ignorée.

Avertissements

Un import réussi peut s'accompagner d'avertissements, visibles dans l'onglet « Sources » (20 au plus, puis « Et N autre(s). ») :

Limites

• 1 000 opérations au plus par spec (au-delà : INVALID_SPEC).
• Le corps de requête n'est exposé que s'il est en JSON.
• Une spec dont le contenu étendu est démesuré est refusée (INVALID_SPEC, « compiled configuration too large »).

Erreurs fréquentes

• UNSUPPORTED_SPEC_VERSION : le fichier n'est pas en OpenAPI 3.0 ou 3.1.
• INVALID_SPEC : ni JSON ni YAML valide, section paths absente, aucune opération, ou trop d'opérations.
• FILE_TOO_LARGE : plus de 5 Mo.
• UNSAFE_URL et UPSTREAM_FETCH_FAILED : l'URL est interdite ou ne répond pas correctement.
• INGESTION_TIMEOUT : l'import a dépassé 28 secondes.

Exemple

Voici une spec minimale qui produit deux outils, listProducts et getOrder :

openapi: 3.0.3
info:
  title: Boutique
  version: 1.0.0
servers:
  - url: https://api.example.com
paths:
  /products:
    get:
      operationId: listProducts
      summary: Liste les produits
      parameters:
        - name: inStock
          in: query
          schema: { type: boolean }
      responses:
        "200": { description: OK }
  /orders/{id}:
    get:
      operationId: getOrder
      summary: Lit une commande par son identifiant
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      responses:
        "200": { description: OK }

Après l'import, l'URL de base https://api.example.com est reprise dans l'onglet « API cible ».