example-petstore.com

Dominio de ejemplo · No es un servicio activo · Las visitas desde el navegador muestran esta página · Las solicitudes a la API reciben 410 Gone

Guía · Swagger Petstore

¿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ónURL base de las solicitudesDescripción de la API y 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

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.
  • Mantener las URL base en la configuración: Configurar clientes de API y SDK.

Fuentes