Geração Swagger/OpenAPI para TypeScript: melhores ferramentas

Geração Swagger/OpenAPI para TypeScript: Guia completo de ferramentas

\n\n

O desenvolvimento de aplicações web modernas em TypeScript está intrinsecamente ligado à criação de clientes API type-safe. Escrever interfaces manualmente para cada endpoint é uma tarefa trabalhosa e propensa a erros. Felizmente, existe uma abordagem poderosa — a geração automática de código TypeScript a partir de especificações OpenAPI (Swagger). Neste artigo, analisaremos detalhadamente as melhores ferramentas para esta tarefa, suas capacidades e exemplos de uso.

\n\n

Por que usar a geração a partir de OpenAPI?

\n

OpenAPI (anteriormente Swagger) é um padrão para descrição de REST APIs. Usando um arquivo de especificação YAML ou JSON, você obtém:

\n

\n
• Tipagem 100% — interfaces TypeScript que correspondem exatamente ao esquema de requisições e respostas
\n
• Sincronização com o backend — ao alterar a API, basta regenerar o código
\n
• Redução de erros — o compilador TypeScript detecta incompatibilidades de tipos durante o desenvolvimento
\n
• Autocompletar na IDE — IntelliSense sugere campos e tipos
\n

\n\n

Principais ferramentas para geração de TypeScript a partir de OpenAPI

\n\n

1. openapi-typescript-codegen (recomendado)

\n

Esta ferramenta ganhou popularidade devido à sua simplicidade e abordagem moderna. Ela gera código limpo e bem estruturado com suporte para axios ou fetch.

\n\n

Instalação:

\n

npm install -D openapi-typescript-codegen

\n\n

Exemplo de uso:

\n

npx openapi-typescript-codegen --input ./spec.yaml --output ./generated --client axios

\n\n

Código gerado:

\n

// generated/models/User.ts\nexport interface User {\n    id: number;\n    name: string;\n    email: string;\n    role: 'admin' | 'user';\n}\n\n// generated/services/UserService.ts\nexport class UserService {\n    public async getUsers(): Promise<User[]> {\n        return this.httpRequest.request({\n            method: 'GET',\n            url: '/users',\n        });\n    }\n}

\n\n

Vantagens:

\n

\n
• Suporte a OpenAPI 3.0 e 3.1
\n
• Geração de modelos, serviços e tipos para requisições
\n
• Geração opcional de hooks para React Query
\n
• Templates personalizáveis via Handlebars
\n

\n\n

2. OpenAPI Generator (openapi-generator)

\n

Gerador oficial da comunidade OpenAPI. Suporta mais de 50 linguagens, incluindo TypeScript (vários geradores).

\n\n

Instalação:

\n

npm install -D @openapitools/openapi-generator-cli

\n\n

Exemplo de uso:

\n

npx openapi-generator-cli generate \\\n    -i spec.yaml \\\n    -g typescript-axios \\\n    -o ./generated

\n\n

Código gerado:

\n

// generated/api.ts\nexport const UsersApiAxiosParamCreator = {\n    getUsers: async (options?: AxiosRequestConfig): Promise<RequestArgs> => {\n        const localVarPath = `/users`;\n        return {\n            url: localVarPath,\n            method: 'GET',\n        };\n    }\n}

\n\n

Características:

\n

\n
• Geradores: typescript-axios, typescript-fetch, typescript-angular
\n
• Suporte a autenticação (OAuth2, API Key)
\n
• Geração de documentação e testes
\n
• Funciona via CLI ou plugins Maven/Gradle
\n

\n\n

3. swagger-typescript-api

\n

Gerador leve e rápido, focado em TypeScript puro sem dependências desnecessárias.

\n\n

Instalação:

\n

npm install -D swagger-typescript-api

\n\n

Exemplo de uso:

\n

npx swagger-typescript-api -p ./spec.yaml -o ./generated -n api.ts

\n\n

Código gerado: