DEV Community

Cover image for 📝 Como Criar Documentação em .NET com TypeSpec
Danilo O. Pinheiro, dopme.io
Danilo O. Pinheiro, dopme.io

Posted on

📝 Como Criar Documentação em .NET com TypeSpec

#csharp #dotnet #typescript

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
Enter fullscreen mode Exit fullscreen mode

Verifique se o tsp está disponível:

tsp --version
Enter fullscreen mode Exit fullscreen mode

🏗️ Criando seu primeiro projeto TypeSpec 

tsp init my-api
cd my-api
Enter fullscreen mode Exit fullscreen mode

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;
}
Enter fullscreen mode Exit fullscreen mode

⚙️ Gerando documentação e OpenAPI

Compile o contrato:

tsp compile main.tsp --emit @typespec/openapi3
Enter fullscreen mode Exit fullscreen mode

Isso gerará o arquivo openapi.yaml.

Você também pode gerar documentação com o plugin:

tsp compile main.tsp --emit @typespec/html
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

💡 Boas práticas com TypeSpec

  • Use @useDependency para 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:

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

Top comments (0)