example-petstore.com

Beispieldomain · Kein aktiver Dienst · Browseraufrufe zeigen diese Seite · API-Anfragen erhalten 410 Gone

Anleitung · Swagger Petstore

Sie suchen den Swagger Petstore?

Der Swagger Petstore ist die Beispiel-API hinter unzähligen Tutorials zu Swagger UI und OpenAPI. Er liegt nicht auf example-petstore.com. Diese Anleitung nennt die echten Adressen, zeigt funktionierende Anfragen und erklärt, wie Sie eine eigene Kopie betreiben, wenn die öffentliche Version stört.

Die echten Adressen

Swagger, die API-Werkzeuge von SmartBear, betreibt zwei öffentliche Versionen des Petstore. Beide bieten dieselben Ressourcen: Haustiere, Bestellungen und Benutzer.

VersionBasis-URL für AnfragenAPI-Beschreibung und 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

Für neue Projekte ist Petstore 3 die beste Wahl: Er folgt der OpenAPI-3.0-Spezifikation, die aktuelle Werkzeuge und Codegeneratoren erwarten. Die Swagger-2.0-Version antwortet weiterhin und kommt in älteren Tutorials vor.

Ausprobieren

Einige Anfragen mit curl. Dieselben Pfade funktionieren in Postman, Insomnia oder einem generierten Client, sobald die Basis-URL auf eine der Adressen oben zeigt.

# Haustiere mit dem Status "available"
curl -H "Accept: application/json" "https://petstore3.swagger.io/api/v3/pet/findByStatus?status=available"

# Ein Haustier anlegen (name und photoUrls sind Pflicht)
curl -X POST "https://petstore3.swagger.io/api/v3/pet" \
  -H "Content-Type: application/json" \
  -d '{"id": 12345, "name": "doggie", "photoUrls": [], "status": "available"}'

# Bestand pro Status, mit dem Testschlüssel
curl -H "api_key: special-key" "https://petstore.swagger.io/v2/store/inventory"

Dasselbe aus PHP, mit Guzzle:

// PHP, Guzzle: Haustiere mit dem Status "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);

Die wichtigsten Pfade: /pet, /pet/findByStatus, /pet/findByTags, /pet/{petId}, /store/inventory, /store/order, /user, /user/login und /user/logout.

Schlüssel und Anmeldung

Der Petstore zeigt zwei Sicherheitsverfahren: einen API-Schlüssel im Header api_key und einen OAuth-2.0-Ablauf (petstore_auth). Die Swagger-2.0-Beschreibung nennt special-key als Schlüssel zum Testen der Autorisierungsfilter. Das sind Demo-Zugangsdaten: Probieren Sie niemals einen echten Schlüssel, ein echtes Token oder Passwort am Petstore aus.

Gemeinsame Testdaten

Alle nutzen denselben öffentlichen Server. Was Sie anlegen, können andere lesen, ändern oder löschen, und findByStatus liefert, was andere hinzugefügt haben, auch seltsame Namen und fehlerhafte Datensätze. Ein Haustier, das Sie gerade angelegt haben, kann schon wieder verschwunden sein.

  • Senden Sie niemals echte personenbezogene Daten, Kundendaten oder echte Zugangsdaten.
  • Bauen Sie keine automatisierten Tests auf dem öffentlichen Server auf: Die Ergebnisse sind unvorhersehbar, und der Server ist manchmal langsam oder meldet einen Fehler (500).
  • Für stabile Ergebnisse betreiben Sie eine eigene Kopie.

Lokal betreiben

Der Petstore ist Open Source (Apache 2.0). Mit Docker läuft er mit einem Befehl:

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

# Swagger UI:          http://localhost:8080
# API-Beschreibung:    http://localhost:8080/api/v3/openapi.json
# Basis-URL:           http://localhost:8080/api/v3

Ohne Docker klonen Sie swagger-api/swagger-petstore und starten ihn mit mvn package jetty:run (ebenfalls auf Port 8080). Eine eigene Kopie startet bei jedem Lauf mit denselben eingebauten Beispieldaten (zehn Haustiere sowie einige Bestellungen und Benutzer), sodass Tests sich jedes Mal gleich verhalten.

Die v1-Adresse, die nicht funktioniert

Die Beispieldatei petstore.yaml aus dem Repository der OpenAPI-Spezifikation nennt http://petstore.swagger.io/v1 als Server, mit dem Pfad /pets. Die Datei veranschaulicht die Spezifikation; dahinter läuft kein Dienst. Ein daraus generierter Client erhält 404 Not Found. Richten Sie ihn auf https://petstore3.swagger.io/api/v3 oder Ihre eigene Kopie; die Pfade unterscheiden sich (/pet statt /pets), generieren Sie den Client also neu aus openapi.json von Petstore 3.

Stattdessen hier gelandet?

example-petstore.com ist ein anderer Name: eine Beispieldomain aus der Google-Dokumentation zu Analytics und Suche. Hier gibt es keine API. Anfragen an Pfade wie /v2/pet auf dieser Domain erhalten 410 Gone mit einer Erklärung in JSON.

  • Prüfen Sie die Basis-URL in Ihrem Code, Ihrer .env-Datei, der Postman-Umgebung oder im Feld servers Ihrer OpenAPI-Beschreibung, und ersetzen Sie example-petstore.com durch eine der Adressen oben.
  • Enthielten diese Anfragen einen echten Schlüssel oder ein Token? Betrachten Sie die Zugangsdaten als offengelegt: Offengelegte Zugangsdaten: was jetzt zu tun ist.
  • Basis-URLs in der Konfiguration halten: API-Clients und SDKs konfigurieren.

Quellen