---
title: "API Swagger Petstore : URL de base, exemples, Docker"
description: "Les vraies adresses de l’API d’exemple Swagger Petstore (v2 et OpenAPI 3), des requêtes qui marchent, la clé de test special-key et l’usage en local."
url: https://example-petstore.com/fr/guides/swagger-petstore
language: fr
---

# 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.

| Version | URL de base des requêtes | Description de l’API et Swagger UI |
| --- | --- | --- |
| Petstore 3 (OpenAPI 3.0) | `https://petstore3.swagger.io/api/v3` | [openapi.json](https://petstore3.swagger.io/api/v3/openapi.json) · [petstore3.swagger.io](https://petstore3.swagger.io/) |
| Petstore (Swagger 2.0) | `https://petstore.swagger.io/v2` | [swagger.json](https://petstore.swagger.io/v2/swagger.json) · [petstore.swagger.io](https://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](https://example-petstore.com/fr/guides/leaked-credentials).
- Garder les URL de base dans la configuration : [Configurer les clients API et les SDK](https://example-petstore.com/fr/guides/api-base-url).

## Guides associés

### [Configurer les clients API et les SDK](https://example-petstore.com/fr/guides/api-base-url)

Sortez les URL de base du code, faites-les pointer vers le service réel et ajoutez une vérification qui empêche les adresses d’exemple d’atteindre la production.

### [Tester avec une API simulée (mock), pas une adresse d’exemple](https://example-petstore.com/fr/guides/mock-api)

Développez et testez avec Prism, WireMock, MSW ou json-server plutôt qu’avec une adresse qui appartient à quelqu’un d’autre.

### [Des valeurs d’exemple sans danger](https://example-petstore.com/fr/guides/example-values)

Domaines, plages IP, numéros d’AS, adresses MAC, numéros de téléphone et cartes de test réservés, pour des exemples sans risque.

## Sources

- [swagger-api/swagger-petstore](https://github.com/swagger-api/swagger-petstore) GitHub
- [Swagger Petstore (OpenAPI 3.0)](https://petstore3.swagger.io/) Swagger
- [Swagger Petstore (Swagger 2.0)](https://petstore.swagger.io/) Swagger
- [swaggerapi/petstore3](https://hub.docker.com/r/swaggerapi/petstore3) Docker Hub
- [OpenAPI Specification example petstore.yaml](https://github.com/OAI/OpenAPI-Specification/blob/3.0.3/examples/v3.0/petstore.yaml) OpenAPI Initiative