A documentação de APIs e contratos de serviços é parte essencial no desenvolvimento moderno com .NET. Com o crescimento de arquiteturas baseadas em microsserviços, sistemas distribuídos e APIs públicas, garantir que os contratos sejam bem definidos e versionados é fundamental.
O TypeSpec (anteriormente conhecido como CADL – Composable API Definition Language) surge como uma ferramenta poderosa da Microsoft para definir contratos de API de forma declarativa e gerar documentação, OpenAPI e até mesmo código de cliente/servidor de forma consistente.
🚀 O que é o TypeSpec?
TypeSpec é uma linguagem DSL (Domain Specific Language) criada para descrever APIs, contratos e modelos de dados em alto nível, que depois podem ser compilados para:
- Documentação (Markdown/HTML)
- OpenAPI (Swagger)
- Especificações REST, gRPC e GraphQL
- Código para .NET, TypeScript, etc.
🧰 Por que usar TypeSpec em projetos .NET?
- ✨ Separa contrato da implementação: favorece governança de APIs.
- 🔁 Geração automática de OpenAPI e SDKs.
- 📦 Facilita integração entre times e documenta versões.
- 🧪 Integra com ferramentas modernas de teste e CI/CD.
📦 Instalando o TypeSpec
Você pode instalar com:
npm install -g @typespec/compiler
Verifique se o tsp está disponível:
tsp --version
🏗️ Criando seu primeiro projeto TypeSpec
tsp init my-api
cd my-api
Isso criará uma estrutura de projeto com o arquivo principal main.tsp.
✍️ Exemplo de contrato TypeSpec
@service({ title: "Minha API", version: "1.0.0" })
namespace MinhaApi;
model Usuario {
id: string;
nome: string;
email: string;
}
@route("/usuarios")
interface UsuarioService {
@get
listar(): Usuario[];
@post
criar(@body novo: Usuario): Usuario;
}
⚙️ Gerando documentação e OpenAPI
Compile o contrato:
tsp compile main.tsp --emit @typespec/openapi3
Isso gerará o arquivo openapi.yaml.
Você também pode gerar documentação com o plugin:
tsp compile main.tsp --emit @typespec/html
E acessar o HTML de documentação gerado.
🤝 Integração com .NET
Com o OpenAPI gerado, use o NSwag ou o AutoRest para gerar clientes/schemas C#.
Exemplo com NSwag:
nswag openapi2csclient /input:openapi.yaml /output:ClienteGerado.cs
💡 Boas práticas com TypeSpec
- Use
@useDependencypara importar modelos comuns. - Estruture contratos por domínio.
- Combine com versionamento (
@versioned). - Gere pipelines automáticas no CI para validar breaking changes.
🧪 Testes e Governança
Com TypeSpec, é possível:
- Validar consistência de contratos antes de deploy.
- Integrar com testes de contrato.
- Automatizar publicação de documentação.
✅ Conclusão
O TypeSpec representa uma nova forma de projetar e manter contratos de APIs, trazendo clareza, reuso e automação ao ecossistema .NET moderno.
Ele separa preocupações, reduz bugs de integração e acelera o desenvolvimento colaborativo entre times.
🤝 Conecte-se Comigo
Se você trabalha com .NET moderno e quer dominar arquitetura, C#, DevOps ou interoperabilidade, vamos conversar:
- 💼 LinkedIn
- ✍️ Medium
- 📬 [email protected]
Que farei, pois? Orarei com o espírito, mas também orarei com o entendimento; cantarei com o espírito, mas também cantarei com o entendimento.
1 Coríntios 14:15