---
title: "API Swagger Petstore: URL base, ejemplos y Docker"
description: "Direcciones reales de la API de ejemplo Swagger Petstore (v2 y OpenAPI 3), solicitudes que funcionan, la clave special-key y cómo ejecutarla en local."
url: https://example-petstore.com/es/guides/swagger-petstore
language: es
---

# ¿Buscas Swagger Petstore?

Swagger Petstore es la API de ejemplo detrás de innumerables tutoriales de Swagger UI y OpenAPI. No está en example-petstore.com. Esta guía recoge sus direcciones reales, muestra solicitudes que funcionan y explica cómo ejecutar tu propia copia cuando la pública se interpone.

## Las direcciones reales

Swagger, las herramientas de API de SmartBear, mantiene dos versiones públicas de Petstore. Ambas ofrecen los mismos recursos: mascotas, pedidos y usuarios.

| Versión | URL base de las solicitudes | Descripción de la API y 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/) |

Para un proyecto nuevo, Petstore 3 es la mejor opción: sigue la especificación OpenAPI 3.0 que esperan las herramientas y los generadores de código actuales. La versión Swagger 2.0 sigue respondiendo y aparece en tutoriales más antiguos.

## Probarla

Algunas solicitudes con `curl`. Las mismas rutas funcionan en Postman, Insomnia o un cliente generado en cuanto la URL base apunta a una de las direcciones anteriores.

```
# Mascotas con el estado "available"
curl -H "Accept: application/json" "https://petstore3.swagger.io/api/v3/pet/findByStatus?status=available"

# Añadir una mascota (name y photoUrls son obligatorios)
curl -X POST "https://petstore3.swagger.io/api/v3/pet" \
  -H "Content-Type: application/json" \
  -d '{"id": 12345, "name": "doggie", "photoUrls": [], "status": "available"}'

# Existencias por estado, con la clave de prueba
curl -H "api_key: special-key" "https://petstore.swagger.io/v2/store/inventory"
```

Lo mismo desde PHP, con Guzzle:

```
// PHP, Guzzle: mascotas con el estado "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);
```

Las rutas principales: `/pet`, `/pet/findByStatus`, `/pet/findByTags`, `/pet/{petId}`, `/store/inventory`, `/store/order`, `/user`, `/user/login` y `/user/logout`.

## Claves e inicio de sesión

Petstore muestra dos esquemas de seguridad: una clave de API en la cabecera `api_key` y un flujo OAuth 2.0 (`petstore_auth`). La descripción Swagger 2.0 indica `special-key` como clave para probar los filtros de autorización. Son credenciales de demostración: nunca pruebes una clave, un token o una contraseña reales en Petstore.

## Datos de prueba compartidos

Todo el mundo usa el mismo servidor público. Lo que creas lo pueden leer, modificar o borrar otras personas, y `findByStatus` devuelve lo que otros han añadido, incluidos nombres extraños y registros mal formados. Una mascota que acabas de crear puede haber desaparecido ya.

- No envíes nunca datos personales reales, datos de clientes ni credenciales reales.
- No bases pruebas automatizadas en el servidor público: los resultados son impredecibles, y a veces va lento o devuelve un error (`500`).
- Para obtener resultados estables, ejecuta tu propia copia.

## Ejecutarla en local

Petstore es de código abierto (Apache 2.0). Con Docker basta un solo comando:

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

# Swagger UI:                 http://localhost:8080
# Descripción de la API:      http://localhost:8080/api/v3/openapi.json
# URL base:                   http://localhost:8080/api/v3
```

Sin Docker, clona `swagger-api/swagger-petstore` e iníciala con `mvn package jetty:run` (también en el puerto 8080). Tu propia copia arranca en cada ejecución con los mismos datos de ejemplo integrados (diez mascotas y algunos pedidos y usuarios), así que las pruebas se comportan igual cada vez.

## La dirección v1 que falla

El archivo de ejemplo `petstore.yaml` del repositorio de la especificación OpenAPI indica `http://petstore.swagger.io/v1` como servidor, con la ruta `/pets`. Ese archivo ilustra la especificación; no hay ningún servicio detrás. Un cliente generado a partir de él recibe `404 Not Found`. Apúntalo a `https://petstore3.swagger.io/api/v3` o a tu propia copia; las rutas son distintas (`/pet` en lugar de `/pets`), así que vuelve a generar el cliente a partir del `openapi.json` de Petstore 3.

## ¿Has acabado aquí por error?

example-petstore.com es otro nombre: un dominio de ejemplo de la documentación de Google sobre Analytics y búsqueda. Aquí no hay ninguna API. Las solicitudes a rutas como `/v2/pet` en este dominio reciben `410 Gone` con una explicación en JSON.

- Revisa la URL base en tu código, tu archivo `.env`, el entorno de Postman o el campo `servers` de tu descripción OpenAPI, y sustituye example-petstore.com por una de las direcciones anteriores.
- ¿Llevaban esas solicitudes una clave o un token reales? Considéralos expuestos: [Credenciales filtradas: qué hacer ahora](https://example-petstore.com/es/guides/leaked-credentials).
- Mantener las URL base en la configuración: [Configurar clientes de API y SDK](https://example-petstore.com/es/guides/api-base-url).

## Guías relacionadas

### [Configurar clientes de API y SDK](https://example-petstore.com/es/guides/api-base-url)

Mantén las URL base fuera del código, haz que apunten al servicio real y añade una comprobación que impida que las direcciones de ejemplo lleguen a producción.

### [Prueba con una API simulada (mock), no con una dirección de ejemplo](https://example-petstore.com/es/guides/mock-api)

Desarrolla y prueba con Prism, WireMock, MSW o json-server en lugar de una dirección que pertenece a otra persona.

### [Valores de ejemplo que puedes usar sin riesgo](https://example-petstore.com/es/guides/example-values)

Dominios, rangos de IP, números de AS, direcciones MAC, teléfonos y tarjetas de prueba reservados para ejemplos inofensivos.

## Fuentes

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