example-petstore.com

Domaine d’exemple · Pas un service réel · Les visites depuis un navigateur affichent cette page · Les requêtes API reçoivent 410 Gone

Guide · Swagger Petstore

Vous cherchez le Swagger Petstore ?

Le Swagger Petstore est l’API d’exemple derrière d’innombrables tutoriels sur Swagger UI et OpenAPI. Il ne se trouve pas sur example-petstore.com. Ce guide donne ses vraies adresses, montre des requêtes qui fonctionnent et explique comment exécuter votre propre copie quand la version publique pose problème.

Les vraies adresses

Swagger, la suite d’outils API de SmartBear, gère deux versions publiques du Petstore. Les deux proposent les mêmes ressources : animaux, commandes et utilisateurs.

VersionURL de base des requêtesDescription de l’API et Swagger UI
Petstore 3 (OpenAPI 3.0)https://petstore3.swagger.io/api/v3openapi.json · petstore3.swagger.io
Petstore (Swagger 2.0)https://petstore.swagger.io/v2swagger.json · petstore.swagger.io

Pour un nouveau projet, Petstore 3 est le meilleur choix : il suit la spécification OpenAPI 3.0 qu’attendent les outils et générateurs de code actuels. La version Swagger 2.0 répond toujours et figure dans des tutoriels plus anciens.

Essayer

Quelques requêtes avec curl. Les mêmes chemins fonctionnent dans Postman, Insomnia ou un client généré, dès que l’URL de base pointe vers l’une des adresses ci-dessus.

# Animaux avec le statut "available"
curl -H "Accept: application/json" "https://petstore3.swagger.io/api/v3/pet/findByStatus?status=available"

# Ajouter un animal (name et photoUrls sont obligatoires)
curl -X POST "https://petstore3.swagger.io/api/v3/pet" \
  -H "Content-Type: application/json" \
  -d '{"id": 12345, "name": "doggie", "photoUrls": [], "status": "available"}'

# Stock par statut, avec la clé de test
curl -H "api_key: special-key" "https://petstore.swagger.io/v2/store/inventory"

La même chose en PHP, avec Guzzle :

// PHP, Guzzle : animaux avec le statut "available"
$client = new GuzzleHttp\Client(['base_uri' => 'https://petstore3.swagger.io/api/v3/']);
$response = $client->get('pet/findByStatus', ['query' => ['status' => 'available']]);
$pets = json_decode((string) $response->getBody(), true);

Les principaux chemins : /pet, /pet/findByStatus, /pet/findByTags, /pet/{petId}, /store/inventory, /store/order, /user, /user/login et /user/logout.

Clés et connexion

Le Petstore illustre deux schémas de sécurité : une clé d’API dans l’en-tête api_key et un flux OAuth 2.0 (petstore_auth). La description Swagger 2.0 indique special-key comme clé pour tester les filtres d’autorisation. Ce sont des identifiants de démonstration : n’essayez jamais une vraie clé, un vrai jeton ou un vrai mot de passe sur le Petstore.

Données de test partagées

Tout le monde utilise le même serveur public. Ce que vous créez peut être lu, modifié ou supprimé par d’autres, et findByStatus renvoie ce que d’autres ont ajouté, y compris des noms étranges et des enregistrements mal formés. Un animal créé il y a un instant peut déjà avoir disparu.

  • N’envoyez jamais de vraies données personnelles, de données clients ni de vrais identifiants.
  • Ne basez pas de tests automatisés sur le serveur public : les résultats sont imprévisibles, et il est parfois lent ou renvoie une erreur (500).
  • Pour des résultats stables, exécutez votre propre copie.

Exécuter en local

Le Petstore est open source (Apache 2.0). Avec Docker, une seule commande suffit :

docker run -d --name petstore -p 8080:8080 swaggerapi/petstore3

# Swagger UI :               http://localhost:8080
# Description de l’API :     http://localhost:8080/api/v3/openapi.json
# URL de base :              http://localhost:8080/api/v3

Sans Docker, clonez swagger-api/swagger-petstore et lancez-le avec mvn package jetty:run (également sur le port 8080). Votre propre copie démarre à chaque lancement avec les mêmes données d’exemple intégrées (dix animaux, plus quelques commandes et utilisateurs), si bien que les tests se comportent de la même façon à chaque exécution.

L’adresse v1 qui échoue

Le fichier d’exemple petstore.yaml du dépôt de la spécification OpenAPI indique http://petstore.swagger.io/v1 comme serveur, avec le chemin /pets. Ce fichier illustre la spécification ; aucun service ne tourne derrière. Un client généré à partir de lui reçoit 404 Not Found. Pointez-le vers https://petstore3.swagger.io/api/v3 ou votre propre copie ; les chemins diffèrent (/pet au lieu de /pets), régénérez donc le client à partir de openapi.json de Petstore 3.

Arrivé ici par erreur ?

example-petstore.com est un autre nom : un domaine d’exemple issu de la documentation de Google sur Analytics et la recherche. Il n’y a pas d’API ici. Les requêtes vers des chemins comme /v2/pet sur ce domaine reçoivent 410 Gone avec une explication en JSON.

  • Vérifiez l’URL de base dans votre code, votre fichier .env, l’environnement Postman ou le champ servers de votre description OpenAPI, et remplacez example-petstore.com par l’une des adresses ci-dessus.
  • Ces requêtes contenaient-elles une vraie clé ou un vrai jeton ? Considérez-le comme exposé : Identifiants divulgués : que faire maintenant.
  • Garder les URL de base dans la configuration : Configurer les clients API et les SDK.

Sources