在找 Swagger Petstore 吗？

真实地址

SmartBear 旗下的 API 工具 Swagger 运行着两个公共版本的 Petstore，两者提供相同的资源：宠物、订单和用户。

新项目最好使用 Petstore 3：它遵循当前工具和代码生成器所预期的 OpenAPI 3.0 规范。Swagger 2.0 版本仍可访问，并出现在较早的教程中。

试用

以下是几个 curl 请求示例。只要把基础 URL 设为上面的某个地址，同样的路径也适用于 Postman、Insomnia 或生成的客户端。

# 状态为 "available" 的宠物
curl -H "Accept: application/json" "https://petstore3.swagger.io/api/v3/pet/findByStatus?status=available"

# 添加一只宠物（name 和 photoUrls 为必填）
curl -X POST "https://petstore3.swagger.io/api/v3/pet" \
  -H "Content-Type: application/json" \
  -d '{"id": 12345, "name": "doggie", "photoUrls": [], "status": "available"}'

# 按状态统计库存（使用测试密钥）
curl -H "api_key: special-key" "https://petstore.swagger.io/v2/store/inventory"

用 PHP 和 Guzzle 实现同样的请求：

// PHP, Guzzle：状态为 "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);

主要路径：/pet、/pet/findByStatus、/pet/findByTags、/pet/{petId}、/store/inventory、/store/order、/user、/user/login 和 /user/logout。

密钥与登录

Petstore 演示了两种安全方案：放在 api_key 请求头中的 API 密钥，以及 OAuth 2.0 流程（petstore_auth）。Swagger 2.0 描述中给出了用于测试授权过滤器的密钥 special-key。这些都是演示用凭据：切勿在 Petstore 上尝试真实的密钥、令牌或密码。

共享的测试数据

所有人都在使用同一台公共服务器。您创建的数据其他人可以读取、修改或删除，findByStatus 返回的是其他人添加的内容，包括奇怪的名称和格式错误的记录。您刚创建的宠物可能转眼就不见了。

• 切勿发送真实的个人数据、客户数据或真实凭据。
• 不要基于公共服务器构建自动化测试：结果不可预测，服务器有时很慢，或会返回错误（500）。
• 如需稳定的结果，请运行自己的副本。

在本地运行

Petstore 是开源软件（Apache 2.0）。使用 Docker 只需一条命令：

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

# Swagger UI:   http://localhost:8080
# API 描述:     http://localhost:8080/api/v3/openapi.json
# 基础 URL:     http://localhost:8080/api/v3

不使用 Docker 时，克隆 swagger-api/swagger-petstore，然后用 mvn package jetty:run 启动（同样在 8080 端口）。自己的副本每次运行时都以相同的内置示例数据（十只宠物，外加若干订单和用户）开始，因此测试每次的表现都一致。

无法使用的 v1 地址

OpenAPI 规范仓库中的示例文件 petstore.yaml 把 http://petstore.swagger.io/v1 列为服务器，路径为 /pets。该文件只用于说明规范，背后并没有运行中的服务。由它生成的客户端会收到 404 Not Found。请改为指向 https://petstore3.swagger.io/api/v3 或自己的副本；由于路径不同（是 /pet 而不是 /pets），请用 Petstore 3 的 openapi.json 重新生成客户端。

误入本站？

example-petstore.com 是另一个名称：它是 Google 关于 Analytics 和搜索的文档中使用的示例域名，这里没有 API。发往此域名上 /v2/pet 等路径的请求会收到 410 Gone，并附有 JSON 格式的说明。

• 检查代码、.env 文件、Postman 环境或 OpenAPI 描述中 servers 字段里的基础 URL，把 example-petstore.com 替换为上面的某个地址。
• 这些请求中是否带有真实的密钥或令牌？请将其视为已泄露：凭据泄露：现在该怎么办。
• 把基础 URL 放在配置中：配置 API 客户端和 SDK。

相关指南

来源

• swagger-api/swagger-petstore GitHub
• Swagger Petstore (OpenAPI 3.0) Swagger
• Swagger Petstore (Swagger 2.0) Swagger
• swaggerapi/petstore3 Docker Hub
• OpenAPI Specification example petstore.yaml OpenAPI Initiative