Pular para o conteúdo principal

@powerduck/x-to-openapi

@powerduck/x-to-openapi é um framework TypeScript extensível que converte comandos curl e coleções do Postman (v2.0 / v2.1.0) em documentos OpenAPI 3.2. Foi criado para pipelines de CI, geração de documentação de APIs e reconstrução de interfaces a partir de requisições HTTP.

Utiliza @powerduck/openapi-parser para validar documentos.

Como funciona​

comando curl → CurlAdapter
coleção do Postman → PostmanAdapter
             ↓
     NormalizedRequest[]
             ↓
     buildOpenApi32() → documento OpenAPI 3.2
             ↓
     validateOpenApi32() → diagnósticos
  1. Um adaptador analisa a origem, como texto curl ou uma coleção do Postman, e produz uma lista de objetos NormalizedRequest.
  2. O gerador combina requisições por método e caminho, infere esquemas, parâmetros de caminho e segurança, e produz um documento OpenAPI 3.2.
  3. O validador verifica a saída em relação ao esquema OpenAPI usando @powerduck/openapi-parser e retorna diagnósticos.

Recursos​

  • Dois adaptadores integrados: CurlAdapter aceita comandos individuais, lotes e a saída «Copy all as cURL» do navegador; PostmanAdapter aceita v2.0/v2.1.0, pastas aninhadas e autenticação herdada.
  • Funções sem configuração: curlToOpenApi e postmanToOpenApi registram o adaptador e convertem em uma chamada.
  • Saída OpenAPI 3.2: cada documento declara openapi: "3.2.0". A validação é habilitada por padrão. Confira os diagnósticos ou ative o modo estrito para rejeitar erros.
  • Combinação de requisições: operações com método e caminho iguais são combinadas; parâmetros de consulta, cabeçalhos, cookies e esquemas de corpo são mesclados estruturalmente.
  • Inferência de parâmetros de caminho: IDs numéricos, UUIDs, ULIDs e segmentos hexadecimais longos viram modelos como /users/{userId} quando variam em pelo menos N amostras.
  • Inferência de segurança: detecta Bearer, Basic e chaves de API em cabeçalhos, consultas ou cookies e gera os securitySchemes correspondentes.
  • Vários tipos de corpo: JSON, XML, form-urlencoded, multipart/form-data com texto e arquivos, GraphQL, texto e binário.
  • Preservação de testes do Postman: pm.test() / pm.expect() são incluídos como x-postman-scripts em cada operação.
  • Diagnósticos: cada problema tem gravidade, código e detalhes de origem quando disponíveis; o modo strict lança exceções em caso de erro.
  • Extensível: implemente SourceAdapter para adicionar origens HAR, HTTPie ou Insomnia.

Arquitetura de plugins​

O framework se baseia em uma pequena interface de adaptador:

interface SourceAdapter<I = unknown> {
  readonly id: string;                       // e.g. "curl", "postman", "har"
  canHandle?(input: unknown): boolean;       // used by "auto" detection
  parse(input: I, context: AdapterContext): Promise<NormalizedRequest[]>;
}

Os adaptadores são registrados em uma instância XToOpenApi por meio de AdapterRegistry:

const converter = new XToOpenApi()
  .register(new CurlAdapter())
  .register(new PostmanAdapter());

// Explicit source id:
await converter.convert("curl", curlText);

// Auto-detect via canHandle():
await converter.convert("auto", someInput);

As funções sem configuração já incluem os dois adaptadores; na maioria dos casos, não é necessário usar o registro diretamente.

Funções auxiliares ou classe?​

Caso de usoAPI
Converter um comando curl ou um lotecurlToOpenApi
Converter uma coleção do Postman como objeto ou stringpostmanToOpenApi
Opções personalizadas, vários adaptadores, detecção "auto" ou adaptador próprionew XToOpenApi()

Próximos passos​

  • Instalação — adicionar o pacote e conhecer as funções sem configuração.
  • Início rápido — converter comandos curl e coleções do Postman e usar um adaptador próprio.
  • Referência da API — todas as exportações, tipos, opções, valores padrão e códigos de diagnóstico.
  • Exemplos — curl, lotes de comandos, coleções do Postman, adaptadores próprios e inferência de caminhos.