Blog

Por que o Exemplo Swagger Petstore é um Design de API REST Ruim?

Ashley Innocent

Ashley Innocent

13 março 2026

Por que o Exemplo Swagger Petstore é um Design de API REST Ruim?

Apidog para empresas

Implantação local

SSO & RBAC

Conforme SOC 2

Explorar Apidog Enterprise

TL;DR

O Swagger Petstore viola princípios REST fundamentais: usa nomes de recursos singulares de forma inconsistente, inclui verbos de ação em URLs, retorna códigos de status HTTP errados, expõe senhas em requisições GET e retorna arrays puros sem metadados. A Modern PetstoreAPI corrige todos esses problemas com um design RESTful adequado, tratamento de erros RFC 9457 e padrões prontos para produção.

Introdução

Há mais de uma década, o Swagger Petstore tem sido o exemplo padrão para aprender OpenAPI. Milhões de desenvolvedores o estudaram, copiaram seus padrões e construíram APIs de produção baseadas em seu design. Há um problema: ele ensina você a construir APIs ruins.

O Swagger Petstore viola princípios REST básicos, inclui vulnerabilidades de segurança e demonstra anti-padrões que prejudicam sistemas em produção. É como aprender a dirigir com um carro que tem os pedais de freio e acelerador trocados – você vai aprender, mas vai aprender errado.

O dano é real. Desenvolvedores que aprenderam com o Swagger Petstore levam esses anti-padrões para o código de produção. APIs são construídas com nomes inconsistentes, métodos HTTP errados e falhas de segurança. Revisões de código ignoram esses problemas porque “é assim que o Petstore faz.”

💡
Se você está construindo ou testando APIs REST, o Apidog ajuda a validar o design da API em relação aos princípios REST, testar o comportamento do endpoint e identificar falhas de design antes que cheguem à produção. Você pode importar especificações OpenAPI, executar testes automatizados e garantir que sua API siga as convenções REST adequadas.
botão

Neste guia, você aprenderá exatamente o que está errado com o Swagger Petstore, por que esses problemas importam e como a Modern PetstoreAPI os corrige com padrões prontos para produção. Você verá comparações lado a lado, entenderá o impacto de cada violação e descobrirá como testar suas APIs corretamente com o Apidog.

O Problema da Herança do Swagger Petstore

O Swagger Petstore foi criado em 2011 como um exemplo simples para a especificação Swagger (agora OpenAPI). Ele cumpriu seu propósito: demonstrar como escrever uma especificação OpenAPI. Mas nunca foi concebido para ser uma referência para o design de APIs REST.

Por que Se Tornou o Padrão De Fato

Quando os desenvolvedores aprendem OpenAPI, eles começam com o exemplo oficial. O Swagger Petstore é esse exemplo. Ele está na documentação, tutoriais e geradores de código. Se você já usou o Swagger UI ou o Swagger Codegen, você o viu.

O problema: desenvolvedores presumem que “exemplo oficial = melhor prática.” Eles copiam os padrões sem questioná-los. Cursos de design de API o usam como ferramenta de ensino. Empresas constroem APIs internas seguindo sua estrutura.

O Custo de Maus Exemplos

Maus exemplos se acumulam ao longo do tempo:

  1. Desenvolvedores júnior aprendem anti-padrões - Eles não sabem que são erros
  2. Geradores de código perpetuam os problemas - SDKs gerados herdam as falhas
  3. Ferramentas de documentação mostram maus exemplos - O Swagger UI exibe o Petstore por padrão
  4. Empresas constroem APIs de produção dessa forma - “Se é bom o suficiente para o Swagger…”

O Swagger Petstore provavelmente influenciou mais designs de API do que qualquer outro exemplo na história. É por isso que suas falhas importam.

Violações Críticas de REST no Swagger Petstore

Vamos examinar as violações REST específicas no Swagger Petstore e por que elas estão erradas.

1. Nomenclatura Inconsistente de Recursos (Plural vs Singular)

A Violação:

GET /pet/{petId}           ← Singular
GET /store/inventory       ← Plural
POST /pet                  ← Singular
GET /user/{username}       ← Singular

Por Que Está Errado:

Recursos REST representam coleções. Uma coleção é plural. Quando você acessa /pets, você está acessando a coleção de pets. Quando você acessa /pets/123, você está acessando o item 123 na coleção de pets.

Misturar singular e plural quebra esse modelo mental. /pet/123 está acessando a coleção de pets ou um único recurso de pet? A inconsistência cria confusão.

Correção da Modern PetstoreAPI:

GET /pets/{petId}          ← Sempre plural
GET /stores/inventory      ← Consistente
POST /pets                 ← Plural para coleção
GET /users/{username}      ← Plural em todo lugar

A Modern PetstoreAPI usa nomes de recursos no plural de forma consistente em todos os endpoints. Verifique a documentação da API REST para a estrutura completa dos endpoints.

2. Verbos de Ação em URLs

A Violação:

GET /pet/findByStatus?status=available
GET /pet/findByTags?tags=tag1,tag2
GET /user/login?username=john&password=secret
GET /user/logout

Por Que Está Errado:

URLs REST devem representar recursos (substantivos), não ações (verbos). O método HTTP é o verbo. GET /pets significa “obter o recurso de pets.” Adicionar findByStatus é redundante – é para isso que servem os parâmetros de consulta.

Verbos de ação em URLs indicam que você está pensando em termos de RPC (Chamada de Procedimento Remoto), não em termos REST. Você está expondo detalhes de implementação em vez de recursos.

Correção da Modern PetstoreAPI:

GET /pets?status=AVAILABLE              ← Recurso + filtro
GET /pets?tags=tag1,tag2                ← Parâmetros de consulta para filtragem
POST /auth/login                        ← Recurso de autenticação separado
POST /auth/logout                       ← Endpoints de autenticação RESTful

A Modern PetstoreAPI usa parâmetros de consulta para filtragem e recursos de autenticação separados. Consulte o guia de autenticação para padrões de autenticação adequados.

3. Códigos de Status HTTP Errados

A Violação:

POST /pet
Response: 200 OK          ← Deveria ser 201 Created

DELETE /pet/{petId}
Response: 200 OK          ← Deveria ser 204 No Content
{
  "message": "Pet deleted"
}

Por Que Está Errado:

Os códigos de status HTTP têm significados específicos:

Usar 200 para tudo quebra a semântica HTTP. Os clientes não conseguem distinguir entre “recurso recuperado” e “recurso criado.” Retornar um corpo com DELETE desperdiça largura de banda – o cliente não precisa de texto de confirmação.

Correção da Modern PetstoreAPI:

POST /pets
Response: 201 Created
Location: /pets/019b4132-70aa-764f-b315-e2803d882a24
{
  "id": "019b4132-70aa-764f-b315-e2803d882a24",
  "name": "Fluffy",
  "status": "AVAILABLE"
}

DELETE /pets/{petId}
Response: 204 No Content
(sem corpo)

A Modern PetstoreAPI usa códigos de status HTTP corretos e inclui cabeçalhos Location para recursos criados. Consulte o guia de códigos de status HTTP para o mapeamento completo.

4. Arrays Puros Sem Metadados

A Violação:

GET /pet/findByStatus?status=available
Response: 200 OK
[
  {"id": 1, "name": "Fluffy"},
  {"id": 2, "name": "Buddy"}
]

Por Que Está Errado:

Retornar arrays puros cria problemas:

Correção da Modern PetstoreAPI:

GET /pets?status=AVAILABLE
Response: 200 OK
{
  "data": [
    {"id": "019b4132-70aa-764f-b315-e2803d882a24", "name": "Fluffy"},
    {"id": "019b4127-54d5-76d9-b626-0d4c7bfce5b6", "name": "Buddy"}
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "totalItems": 45,
    "totalPages": 3
  },
  "links": {
    "self": "/pets?status=AVAILABLE&page=1",
    "next": "/pets?status=AVAILABLE&page=2",
    "last": "/pets?status=AVAILABLE&page=3"
  }
}

A Modern PetstoreAPI envolve todas as coleções em objetos com metadados e links HATEOAS. Consulte o guia de paginação para detalhes de implementação.

5. Ausência de Padrões de Erro

A Violação:

Response: 400 Bad Request
{
  "code": 400,
  "message": "Invalid input"
}

Por Que Está Errado:

Este formato de erro não é padrão e fornece informações mínimas:

Correção da Modern PetstoreAPI:

Response: 400 Bad Request
Content-Type: application/problem+json
{
  "type": "https://petstoreapi.com/errors/validation-error",
  "title": "Validation Error",
  "status": 400,
  "detail": "Request validation failed",
  "instance": "/pets",
  "errors": [
    {
      "field": "name",
      "message": "Name is required",
      "code": "REQUIRED_FIELD"
    },
    {
      "field": "status",
      "message": "Status must be one of: AVAILABLE, PENDING, SOLD",
      "code": "INVALID_ENUM"
    }
  ]
}

A Modern PetstoreAPI usa RFC 9457 Problem Details para todos os erros. Consulte o guia de tratamento de erros para o formato completo de erro.

Desastres de Segurança no Design Antigo

Além das violações REST, o Swagger Petstore possui sérios problemas de segurança.

Requisição GET com Senhas

Por Que É Um Desastre:

Senhas em requisições GET aparecem em:

Esta é uma vulnerabilidade de segurança crítica. Senhas nunca devem estar em URLs.

Correção da Modern PetstoreAPI:

POST /auth/login
Content-Type: application/json
{
  "username": "john",
  "password": "secret123"
}

Response: 200 OK
{
  "accessToken": "eyJhbGc...",
  "refreshToken": "eyJhbGc...",
  "expiresIn": 3600
}

A Modern PetstoreAPI usa POST para autenticação com corpos JSON. Senhas nunca aparecem em URLs. Consulte o guia de autenticação para padrões OAuth 2.0 e JWT.

Chaves de API em Parâmetros de Consulta

Por Que Está Errado:

Chaves de API em parâmetros de consulta têm os mesmos problemas que senhas em URLs:

Correção da Modern PetstoreAPI:

GET /pets/019b4132-70aa-764f-b315-e2803d882a24
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

A Modern PetstoreAPI usa cabeçalhos Authorization padrão para chaves de API e tokens. Consulte o guia de segurança para padrões de autenticação.

Como a Modern PetstoreAPI Corrige Esses Problemas

A Modern PetstoreAPI foi construída do zero para demonstrar um design de API REST adequado. Aqui está o que a torna diferente:

Design REST Pronto para Produção

Padrões Modernos

Suporte Multi-Protocolo

Ao contrário do Swagger Petstore (apenas REST), a Modern PetstoreAPI suporta:

Consulte o guia de protocolos para detalhes de implementação.

Lógica de Negócios Real

A Modern PetstoreAPI inclui recursos realistas:

Verifique a documentação da API para o conjunto completo de recursos.

Testando o Design da API REST com Apidog

O Apidog ajuda você a validar o design da API REST e a identificar violações antes que cheguem à produção.

Importar e Validar Especificações OpenAPI

# Importar especificação da Modern PetstoreAPI
1. Abrir Apidog
2. Clicar em "Importar" → "OpenAPI"
3. Inserir: https://petstoreapi.com/openapi.json
4. Apidog valida a especificação e cria casos de teste

O Apidog detecta automaticamente:

Testar Princípios REST

Crie casos de teste que verifiquem a conformidade REST:

Teste: Nomes de Recursos São Plurais

// Script de teste do Apidog
pm.test("Endpoint uses plural resource name", function() {
  const url = pm.request.url.toString();
  pm.expect(url).to.match(/\/pets\/|\/orders\/|\/users\//);
  pm.expect(url).to.not.match(/\/pet\/|\/order\/|\/user\//);
});

Teste: Códigos de Status Corretos

pm.test("POST returns 201 Created", function() {
  if (pm.request.method === "POST") {
    pm.response.to.have.status(201);
    pm.response.to.have.header("Location");
  }
});

pm.test("DELETE returns 204 No Content", function() {
  if (pm.request.method === "DELETE") {
    pm.response.to.have.status(204);
    pm.expect(pm.response.text()).to.be.empty;
  }
});

Teste: Coleções Têm Metadados

pm.test("Collection response includes pagination", function() {
  const response = pm.response.json();
  pm.expect(response).to.have.property("data");
  pm.expect(response).to.have.property("pagination");
  pm.expect(response.pagination).to.have.property("page");
  pm.expect(response.pagination).to.have.property("totalItems");
});

Comparar Petstore Antigo vs. Novo

Importe ambas as especificações para o Apidog e execute comparações lado a lado:

  1. Importar Swagger Petstore: https://petstore.swagger.io/v2/swagger.json
  2. Importar Modern PetstoreAPI: https://petstoreapi.com/openapi.json
  3. Executar testes automatizados em ambos
  4. Comparar resultados para ver as diferenças

O Apidog destacará as violações de design no Swagger Petstore e mostrará como a Modern PetstoreAPI as corrige.

Guia de Migração: Do Petstore Antigo para o Design Moderno

Se você construiu uma API baseada no Swagger Petstore, veja como migrar para um design REST adequado:

Passo 1: Corrigir Nomes de Recursos

Antes:

GET /pet/{petId}
POST /pet
DELETE /pet/{petId}

Depois:

GET /pets/{petId}
POST /pets
DELETE /pets/{petId}

Estratégia de Migração:

Passo 2: Remover Verbos de Ação

Antes:

GET /pet/findByStatus?status=available
GET /pet/findByTags?tags=tag1,tag2

Depois:

GET /pets?status=AVAILABLE
GET /pets?tags=tag1,tag2

Estratégia de Migração:

Passo 3: Corrigir Códigos de Status HTTP

Antes:

POST /pet → 200 OK
DELETE /pet/{petId} → 200 OK com corpo

Depois:

POST /pets → 201 Created com cabeçalho Location
DELETE /pets/{petId} → 204 No Content (sem corpo)

Estratégia de Migração:

Passo 4: Empacotar Coleções

Antes:

[
  {"id": 1, "name": "Fluffy"},
  {"id": 2, "name": "Buddy"}
]

Depois:

{
  "data": [...],
  "pagination": {...},
  "links": {...}
}

Estratégia de Migração:

Passo 5: Implementar Erros RFC 9457

Antes:

{
  "code": 400,
  "message": "Invalid input"
}

Depois:

{
  "type": "https://petstoreapi.com/errors/validation-error",
  "title": "Validation Error",
  "status": 400,
  "detail": "Request validation failed",
  "errors": [...]
}

Estratégia de Migração:

Impacto no Mundo Real de um Design de API Ruim

Um design de API ruim tem custos reais:

Confusão do Desenvolvedor

Quando as APIs violam os princípios REST, os desenvolvedores perdem tempo:

Custo: Horas de tempo de desenvolvedor por integração

Bugs do Cliente

APIs inconsistentes levam a bugs do lado do cliente:

Custo: Incidentes de produção e impacto no cliente

Vulnerabilidades de Segurança

Falhas de design criam riscos de segurança:

Custo: Vazamentos de dados e violações de conformidade

Dívida Técnica

Maus exemplos se acumulam ao longo do tempo:

Custo: Carga de manutenção de longo prazo

Conclusão

O Swagger Petstore cumpriu seu propósito como um exemplo simples de OpenAPI, mas é hora de seguir em frente. Suas violações REST, problemas de segurança e anti-padrões influenciaram muitas APIs em produção.

A Modern PetstoreAPI fornece a implementação de referência que a indústria precisa: design REST adequado, padrões modernos, suporte multi-protocolo e padrões prontos para produção. Use-a como seu recurso de aprendizado e referência para o design de APIs.

Teste suas APIs com o Apidog para identificar violações de design precocemente. Importe suas especificações OpenAPI, execute testes automatizados e garanta que suas APIs sigam os princípios REST antes de chegarem à produção.

Próximos Passos:

  1. Explore a documentação da Modern PetstoreAPI
  2. Compare o design da sua API com os padrões da Modern PetstoreAPI
  3. Importe sua especificação OpenAPI para o Apidog para validação
  4. Corrija violações REST usando o guia de migração acima
  5. Adote a RFC 9457 para tratamento de erros

A era de maus exemplos de API acabou. Construa APIs da maneira certa com a Modern PetstoreAPI.

FAQ

Por que o Swagger criou um exemplo ruim?

O Swagger Petstore foi criado em 2011 como uma simples demonstração da especificação Swagger. Não foi concebido para ser uma referência de design de API REST. O problema é que ele se tornou o exemplo padrão de fato, e suas falhas foram copiadas por milhões de desenvolvedores.

Devo parar de usar o Swagger Petstore?

Sim, para aprender design de API REST. Use a Modern PetstoreAPI em vez disso. Ela demonstra princípios REST adequados, padrões modernos e padrões prontos para produção. O Petstore antigo ensina anti-padrões que prejudicam sistemas em produção.

A Modern PetstoreAPI está pronta para produção?

Sim. A Modern PetstoreAPI inclui lógica de negócios realista, tratamento de erros adequado, autenticação, limitação de taxa e recursos de segurança. Você pode implantá-la com modificações mínimas ou usá-la como referência para o design da sua própria API.

Como eu testo se minha API segue os princípios REST?

Importe sua especificação OpenAPI para o Apidog e execute testes automatizados. O Apidog valida a nomenclatura de recursos, códigos de status HTTP, estruturas de resposta e padrões de segurança. Você também pode comparar sua API lado a lado com a Modern PetstoreAPI.

Qual é o maior erro no Swagger Petstore?

Usar GET /user/login com senhas em parâmetros de consulta. Isso expõe senhas no histórico do navegador, logs do servidor e cabeçalhos referer – uma vulnerabilidade de segurança crítica. Sempre use POST com corpos JSON para autenticação.

Posso migrar dos padrões do Swagger Petstore gradualmente?

Sim. Suporte endpoints antigos e novos durante um período de transição. Adicione avisos de depreciação aos endpoints antigos, atualize a documentação e monitore o uso. Remova os endpoints antigos depois que os clientes migrarem (geralmente 6-12 meses).

A Modern PetstoreAPI suporta GraphQL e gRPC?

Sim. Ao contrário do Swagger Petstore (apenas REST), a Modern PetstoreAPI suporta múltiplos protocolos: REST, GraphQL, gRPC, WebSocket, SSE, MQTT, Webhooks e MCP. Consulte o guia de protocolos para detalhes.

Como convenço minha equipe a corrigir nosso design de API?

Mostre a eles os custos reais: confusão do desenvolvedor, bugs do cliente, vulnerabilidades de segurança e dívida técnica. Use o Apidog para demonstrar as violações em sua API atual. Compare seu design com a Modern PetstoreAPI e mostre as melhorias.

Pratique o design de API no Apidog

Descubra uma forma mais fácil de construir e usar APIs

Cadastre-se gratuitamenteBaixar