example-petstore.com

Voorbeelddomein · Geen echte dienst · Bezoekers met een browser zien deze pagina · API-verzoeken krijgen 410 Gone

Gids · Swagger Petstore

Op zoek naar de Swagger Petstore?

De Swagger Petstore is de voorbeeld-API achter talloze tutorials over Swagger UI en OpenAPI. Hij staat niet op example-petstore.com. Deze gids geeft de echte adressen, laat werkende verzoeken zien en legt uit hoe je een eigen kopie draait als de openbare versie in de weg zit.

De echte adressen

Swagger, de API-tooling van SmartBear, houdt twee openbare versies van de Petstore in de lucht. Beide hebben dezelfde onderdelen: huisdieren, bestellingen en gebruikers.

VersieBasis-URL voor verzoekenAPI-beschrijving en 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

Voor een nieuw project is Petstore 3 de beste keuze: die volgt de OpenAPI 3.0-specificatie die huidige tools en codegeneratoren verwachten. De Swagger 2.0-versie antwoordt nog steeds en komt voor in oudere tutorials.

Uitproberen

Een paar verzoeken met curl. Dezelfde paden werken in Postman, Insomnia of een gegenereerde client zodra de basis-URL op een van de adressen hierboven staat.

# Huisdieren met de status "available"
curl -H "Accept: application/json" "https://petstore3.swagger.io/api/v3/pet/findByStatus?status=available"

# Een huisdier toevoegen (name en photoUrls zijn verplicht)
curl -X POST "https://petstore3.swagger.io/api/v3/pet" \
  -H "Content-Type: application/json" \
  -d '{"id": 12345, "name": "doggie", "photoUrls": [], "status": "available"}'

# Voorraad per status, met de testsleutel
curl -H "api_key: special-key" "https://petstore.swagger.io/v2/store/inventory"

Hetzelfde vanuit PHP, met Guzzle:

// PHP, Guzzle: huisdieren met de 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);

De belangrijkste paden: /pet, /pet/findByStatus, /pet/findByTags, /pet/{petId}, /store/inventory, /store/order, /user, /user/login en /user/logout.

Sleutels en inloggen

De Petstore laat twee manieren van beveiligen zien: een API-sleutel in de header api_key en een OAuth 2.0-flow (petstore_auth). De Swagger 2.0-beschrijving noemt special-key als sleutel om de autorisatiefilters te testen. Dat zijn demogegevens: probeer nooit een echte sleutel, een echt token of een echt wachtwoord uit op de Petstore.

Gedeelde testgegevens

Iedereen gebruikt dezelfde openbare server. Wat je aanmaakt, kunnen anderen lezen, wijzigen of verwijderen, en findByStatus geeft terug wat anderen hebben toegevoegd, inclusief vreemde namen en kapotte records. Een huisdier dat je net hebt aangemaakt, kan alweer weg zijn.

  • Stuur nooit echte persoonsgegevens, klantgegevens, of echte sleutels en wachtwoorden.
  • Bouw geen geautomatiseerde tests op de openbare server: de uitkomsten zijn onvoorspelbaar, en de server is soms traag of geeft een fout (500).
  • Voor stabiele resultaten draai je een eigen kopie.

Lokaal draaien

De Petstore is open source (Apache 2.0). Met Docker draait hij met één opdracht:

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

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

Zonder Docker kloon je swagger-api/swagger-petstore en start je hem met mvn package jetty:run (ook op poort 8080). Een eigen kopie begint bij elke start met dezelfde ingebouwde voorbeeldgegevens (tien huisdieren plus een paar bestellingen en gebruikers), zodat tests zich elke keer hetzelfde gedragen.

Het v1-adres dat niet werkt

Het voorbeeldbestand petstore.yaml uit de repository van de OpenAPI-specificatie noemt http://petstore.swagger.io/v1 als server, met het pad /pets. Dat bestand illustreert de specificatie; er draait geen dienst achter. Een client die ervan gegenereerd is, krijgt 404 Not Found. Richt hem op https://petstore3.swagger.io/api/v3 of je eigen kopie; de paden verschillen (/pet in plaats van /pets), dus genereer de client opnieuw uit openapi.json van Petstore 3.

Hier beland in plaats van bij de Petstore?

example-petstore.com is een andere naam: een voorbeelddomein uit de documentatie van Google over Analytics en zoeken. Er draait geen API. Verzoeken naar paden als /v2/pet op dit domein krijgen 410 Gone met een uitleg in JSON.

  • Controleer de basis-URL in je code, je .env-bestand, de Postman-omgeving of het veld servers van je OpenAPI-beschrijving, en vervang example-petstore.com door een van de adressen hierboven.
  • Zat er een echte sleutel of token in die verzoeken? Beschouw die als uitgelekt: Gelekte sleutels: wat je nu doet.
  • Basis-URL’s in de configuratie houden: API-clients en SDK’s configureren.

Bronnen