Design de API REST com versionamento e documentação OpenAPI

Projete uma API REST completa para [NOME DO PROJETO], um [TIPO: SaaS/marketplace/fintech] construído com [NODE.JS + EXPRESS/FASTIFY/NESTJS] e [POSTGRESQL/MYSQL].

**Contexto:**
- Recursos principais: [LISTA DE ENTIDADES: usuários, pedidos, produtos, etc.]
- Consumidores: [FRONTEND SPA, APP MOBILE, PARCEIROS EXTERNOS]
- Volume esperado: [NÚMERO] requisições/segundo
- Autenticação: [JWT/API KEY/OAUTH2]

**1) Convenções e Naming:**
- Estrutura de URLs (plural, kebab-case, hierarquia)
- Métodos HTTP por operação (GET, POST, PUT, PATCH, DELETE)
- Status codes padronizados (sucesso, erro cliente, erro servidor)
- Formato de resposta padrão: `{ data, meta, errors }`
- Envelope de erro: `{ code, message, details, timestamp }`

**2) Versionamento:**
- Estratégia: URL path (/v1/) vs. header vs. query param — recomende e justifique
- Política de depreciação (timeline, headers de aviso)
- Manutenção de compatibilidade retroativa

**3) Paginação, Filtro e Ordenação:**
- Cursor-based pagination (para feeds) vs. offset (para tabelas)
- Filtros via query params: `?status=ativo&created_after=2026-01-01`
- Ordenação: `?sort=-created_at,name`
- Campos parciais: `?fields=id,name,email`
- Resposta meta: `{ total, page, per_page, next_cursor }`

**4) Autenticação e Autorização:**
- Fluxo de autenticação JWT (access + refresh tokens)
- Middleware de autorização por role (admin, user, partner)
- Rate limiting por API key (tiers: free, pro, enterprise)
- CORS configuração por ambiente

**5) Documentação OpenAPI 3.1:**
- Schema de cada endpoint com exemplos
- Modelos de request/response tipados
- Autenticação documentada (securitySchemes)
- Geração automática com Swagger UI
- Postman collection exportada

Inclua exemplos completos para os endpoints de [RECURSO PRINCIPAL] (CRUD + busca + ações customizadas).