---
title: "Swagger Petstore API: basis-URL’s, voorbeelden, Docker"
description: "De echte adressen van de voorbeeld-API Swagger Petstore (v2 en OpenAPI 3), werkende verzoeken, de testsleutel special-key en de API lokaal draaien."
url: https://example-petstore.com/nl/guides/swagger-petstore
language: nl
---

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

| Versie | Basis-URL voor verzoeken | API-beschrijving en 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/) |

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](https://example-petstore.com/nl/guides/leaked-credentials).
- Basis-URL’s in de configuratie houden: [API-clients en SDK’s configureren](https://example-petstore.com/nl/guides/api-base-url).

## Verwante gidsen

### [API-clients en SDK’s configureren](https://example-petstore.com/nl/guides/api-base-url)

Houd basis-URL’s buiten de code, laat ze naar de echte dienst wijzen en voeg een controle toe die voorkomt dat voorbeeldadressen in productie belanden.

### [Test tegen een mock-API, niet tegen een voorbeeldadres](https://example-petstore.com/nl/guides/mock-api)

Ontwikkel en test tegen Prism, WireMock, MSW of json-server in plaats van een adres dat van iemand anders is.

### [Voorbeeldwaarden die je veilig kunt gebruiken](https://example-petstore.com/nl/guides/example-values)

Gereserveerde domeinen, IP-reeksen, AS-nummers, MAC-adressen, telefoonnummers en testkaarten voor voorbeelden die onschadelijk blijven.

## Bronnen

- [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