TypeSpec: Uma alternativa para especificar APIs Rest

Fala Dev, tudo em riba?

Se você trabalha com codificação há algum tempo, muito provavelmente já precisou criar uma API REST — nem que fosse só uns endpoints básicos, aquele CRUDizinho — ou, pelo menos, já consumiu algum endpoint de uma API por aí.

Bom, caso você já tenha codificado uma API, provavelmente se deparou com a necessidade de especificar os endpoints existentes nela ou, quem sabe, até tenha soltado uns palavrões quando tentou consumir algum endpoint de uma API mal documentada e ficou batendo cabeça.

Existem inúmeras formas de criar uma especificação para uma API, e neste artigo vou te apresentar uma que achei bem interessante: o TypeSpec.

O que é TypeSpec?

O TypeSpec é uma linguagem criada pela Microsoft dedicada à modelagem e especificação de APIs. Ele foi feito para ajudar desenvolvedores a:

Descrever contratos (endpoints, tipos de dados, autenticação, erros etc.);
Gerar documentação e código automaticamente;
Padronizar a forma como APIs são descritas, reduzindo riscos de inconsistências;

Diferente de outras soluções como OpenAPI/Swagger, o TypeSpec se parece muito mais com uma linguagem de programação, tornando a curva de aprendizado bem leve para quem já escreve em TypeScript ou C#.

Por que usar TypeSpec?

Além da facilidade de leitura (visual clean e código organizado), o principal atrativo é a padronização, reaproveitamento de código e facilidade de manutenção do código. Outros motivos para usar são:

Menos erros humanos: contratos de API centralizados e validados por ferramentas.
Geração automática: a mesma definição pode gerar documentação, SDKs, OpenAPI, entre outros.
Extensibilidade: fácil adicionar regras, restrições e customizações.

Como funciona na prática?

O TypeSpec utiliza arquivos .tsp (TypeSpec files). Aqui vai um exemplo básico de como descrever um serviço simples:

import "@typespec/rest";

@service({
  title: "Catálogo de Produtos",
  version: "1.0.0"
})
model Produto {
  id: string;
  nome: string;
  preco: float32;
}

@route("/produtos")
resource Produtos {
  @get
  list(): Produto[];
}

Nesse exemplo, estamos criando um modelo de produto e um endpoint para listar todos os produtos (algo bem similar ao que faríamos em TypeScript ou C#).

Gerando documentação e código automático

Depois de definir sua API em TypeSpec, é simples gerar diferentes artefatos usando o CLI:

tsp compile

Esse comando pode gerar:

Documentação (em diferentes formatos);
Especificação OpenAPI (pra integração com outras ferramentas);
SDKs automatizados;

Tudo isso a partir de um mesmo ponto de definição, facilitando a manutenção e garantindo consistência.

Vantagens e recursos do TypeSpec

Entre os principais destaques do TypeSpec para o dia a dia:

Interoperabilidade: fácil integrar com outras ferramentas do ecossistema;
Padrões reutilizáveis: crie e aplique patterns de autenticação, formatação, erro, etc.;
Experiência para devs: sintaxe gostosa de ler e fácil de aprender;
Escalabilidade: ideal para APIs pequenas ou grandes corporações;
Geração OpenAPI sem dor: exportação e integração automáticas;

Começando no TypeSpec

Para testar agora mesmo:

Instale o CLI com npm install -g @typespec/cli;
Crie um arquivo .tsp e aplique seus exemplos (ou pode começar com o exemplo acima);
Gere os artefatos com tsp compile;

A documentação oficial traz muitos exemplos para APIs REST, GraphQL, gRPC e casos complexos. Vale dar uma olhada para se aprofundar!

Conclusão

O TypeSpec chegou para simplificar — e muito — a vida de quem projeta e documenta APIs. Aposte na padronização, gere código automaticamente e foque no que realmente importa: entregar valor com segurança e eficiência.

Se curtiu o assunto, no vídeo abaixo eu mostro em detalhes como utilizar o TypeSpec, demonstrando o quanto ele é simples e produtivo 👇

Fico por aqui e até a próxima!

Intellecti