Vamos falar sobre documentação?

A documentação de APIs define regras, contratos, validações de entrada e outros aspectos essenciais para garantir a comunicação eficiente entre sistemas e desenvolvedores.

Antes de existirem ferramentas que automatizassem a documentação, esse processo era feito manualmente, o que tornava os documentos propensos a erros e difíceis de manter. Foi nesse contexto que surgiu o Swagger, juntamente com a especificação OpenAPI, revolucionando a maneira como documentações robustas e de alta qualidade são construídas.

Com o Swagger, tornou-se possível gerar código automaticamente a partir de uma especificação OpenAPI e vice-versa, permitindo que os desenvolvedores focassem mais na criação do produto.

TypeSpec: A evolução da documentação de APIs

Em abril de 2024, a Microsoft lançou o TypeSpec, uma linguagem declarativa baseada em TypeScript e C#, que permite gerar documentação em diversos formatos, como OpenAPI 3 e clientes HTTP em diferentes linguagens de programação.

Quando usar TypeSpec?

O TypeSpec é útil para diversas situações, especialmente nos seguintes cenários:

• Desenvolvimento orientado à documentação (Design First API): Permite criar a documentação primeiro e depois desenvolver a API baseada nela.
• Projetos que exigem múltiplos formatos de saída, como OpenAPI 3, clientes HTTP para diversas linguagens de programação e controle de versionamento.

Vantagens do TypeSpec

• Linguagem simples e robusta: Usa uma abordagem totalmente declarativa para documentação de APIs.
• Modularidade: Permite separar declarações por modelos de entrada e saída, interfaces, serviços, etc.
• Automação completa: Geração automática de OpenAPI, SDKs e documentação.

Conclusão

O TypeSpec facilita a documentação e padronização de APIs, permitindo um desenvolvimento mais organizado, eficiente e sem retrabalho. Com ele, equipes podem criar documentações precisas e gerar código automaticamente, garantindo consistência e confiabilidade no desenvolvimento de software.

Rodando o projeto

Para executar a compilação da documentação, se faz necessário ter o Node.JS 20 ou superior.

Instalando o typespec:

    npm install -g @typespec/compiler

Instalando as dependências

Dentro da pasta do projeto, execute o comando:

    tsp install

Compilando a documentação

    tsp compile .

O arquivo com a especificação Openapi estará disponível em "tsp-output" Para visualizar a mesma em uma interface gráfica, você pode colar o conteúdo do arquivo no Swagger Editor ou usar alguma solução para rodar o editor do Swagger localmente, como a Extensão do VS Code