O Fim da Documentação Desatualizada no Delphi: Swagger & Dext Doc

“Código sem documentação é código temporário.” Essa máxima guia o desenvolvimento do Dext Framework desde sua concepção. Mas sejamos honestos: manter documentação atualizada é uma das tarefas mais ingratas do desenvolvimento.

Quem já trabalhou em projetos longos conhece o ciclo: você cria a API, escreve um lindo PDF ou Wiki, e duas semanas depois… a documentação já é mentirosa. Um parâmetro mudou, um endpoint novo surgiu, e o documento ficou esquecido na gaveta.

O Dext Framework resolve esse problema atacando a causa raiz: A documentação não deve ser um artefato separado; ela deve nascer do próprio código.

Neste artigo, apresento as duas ferramentas nativas do Dext que automatizam esse processo: o Swagger/OpenAPI (para quem consome sua API) e o dext doc (para quem mantém seu código).

---

1. Swagger/OpenAPI: Sua API Documentada em Tempo Real

A melhor documentação é aquela que você não precisa abrir o Word para escrever. O Dext traz suporte de primeira classe ao padrão OpenAPI, permitindo que a especificação da sua API viva junto com a implementação.

Não é um “add-on” ou componente de terceiro. É nativo.

uses
  Dext.Swagger.Middleware,
  Dext.OpenAPI.Fluent;

App.Configure(procedure(App: IApplicationBuilder)
begin
  // Uma linha e sua documentação interativa está no ar
  App.UseSwagger;

  // Seus endpoints aqui...
end);

A Magia da API Fluente

Esqueça arquivos XML complexos ou comentários gigantescos que poluem o código. O Dext utiliza uma DSL (Domain Specific Language) fluente e atributos modernos. Você documenta a intenção do endpoint no momento em que o define:

SwaggerEndpoint.From(App.MapGet('/api/users/{id}', GetUserHandler))
  .Summary('Buscar usuário por ID')
  .Description('Retorna os detalhes completos do usuário.')
  .Tag('Usuários')
  .Response(200, TypeInfo(TUser), 'Usuário encontrado')
  .Response(404, TypeInfo(TErrorResponse), 'Usuário não encontrado');

O resultado? Se você alterar o tipo de retorno no código, o Swagger reflete a mudança imediatamente. A documentação nunca fica dessincronizada.

Schemas Inteligentes com Atributos

Para seus DTOs e entidades, usamos atributos que enriquecem a documentação visual:

type
  [SwaggerSchema('User', 'Representa um cliente ativo')]
  TUser = record
    [SwaggerProperty('Identificador único')]
    [SwaggerExample('1050')]
    Id: Integer;

    [SwaggerProperty('E-mail corporativo')]
    [SwaggerFormat('email')] // Validação visual no Swagger UI
    Email: string;
  end;

---

2. dext doc: A Ferramenta que o Delphi Merecia

Durante o desenvolvimento do Dext, eu tinha um requisito inegociável: a documentação interna da API (classes, units, arquitetura) precisava ser impecável e automática. Tentei usar as ferramentas Open Source disponíveis no mercado… e me frustrei.

Algumas não entendiam sintaxes modernas (como Generics avançados ou Atributos), outras geravam um HTML com visual datado, e a maioria quebrava ao tentar analisar a complexidade do código do framework.

Percebi que se eu quisesse qualidade, teria que construí-la. Assim nasceu o dext doc.

O dext doc ficou tão bom que ele transcendeu o próprio framework. Hoje, ele é uma ferramenta standalone poderosa que pode ser usada em qualquer projeto Delphi, use você o Dext Framework ou não.

Por que ele é diferente?

Diferente de geradores baseados apenas em comentários XML, o dext doc realiza uma análise profunda da AST (Árvore de Sintaxe Abstrata) do seu código.

• Entende Delphi Moderno: Generics, Anonymous Methods, Attributes — ele lê tudo nativamente.
• Diagramas Automáticos (Mermaid): Ele não apenas lista métodos; ele desenha a arquitetura. Cada classe ganha um diagrama UML gerado na hora, mostrando heranças e interfaces.
• Zero Configuração: Não precisa instalar Node.js, Java, Graphviz ou dependências obscuras. É um executável simples: apontou, gerou.

Sucesso com Semantic XML

Além da análise estatística, o dext doc respeita o padrão de Semantic XML Comments. Isso significa que você pode enriquecer sua documentação técnica com descrições detalhadas, parâmetros e retornos usando a sintaxe que o próprio Delphi utiliza para o Help Insight:

  /// <summary>
  ///   Middleware that validates JWT tokens and populates the User principal.
  /// </summary>
  TJwtAuthenticationMiddleware = class(TInterfacedObject, IMiddleware)

  // ...

  /// <summary>
  ///   Specifies a custom name for a field in the JSON output.
  /// </summary>
  JsonNameAttribute = class(DextJsonAttribute)
  private
    FName: string;
  public
    /// <summary>
    ///   Initializes a new instance of the JsonNameAttribute class.
    /// </summary>
    /// <param name="AName">
    ///   The custom name to be used in the JSON.
    /// </param>
    constructor Create(const AName: string);
    property Name: string read FName;
  end;

Sua Porta de Entrada para o Moderno

Talvez você ainda não possa migrar seu ERP legado para a arquitetura do Dext hoje. Mas você pode começar a documentá-lo com a qualidade do Dext agora mesmo.

Rode o comando na pasta do seu projeto atual:

dext doc --input ./SeuProjetoLegado --output ./Docs --title "Documentação ERP"

E veja seu código ganhar vida em um site moderno, responsivo, com busca instantânea e Dark Mode. É a maneira mais segura e imediata de elevar o nível profissional do seu projeto.

---

3. Workflow Integrado: A Cultura da Documentação

A filosofia do Dext não é apenas fornecer classes úteis, é elevar a barra da engenharia de software no ecossistema Delphi.

Ao adotar essas ferramentas, você muda a cultura do time:

1. No Pull Request: O revisor verifica se os atributos [Swagger] estão claros.
2. No CI/CD: O pipeline roda o dext doc e publica a nova versão do site automaticamente.
3. No Onboarding: O novo dev recebe o link da doc e consegue navegar visualmente pela arquitetura.

Conclusão

Documentação não precisa ser burocracia. Quando a ferramenta certa trabalha a seu favor, documentar se torna uma consequência natural de escrever bom código.

Experimente rodar o dext doc no seu projeto hoje e veja sua arquitetura com outros olhos.

---

🚧 Nota de Transparência: O Desafio do Parser

O dext doc é uma ferramenta ambiciosa. Para gerar diagramas e documentação rica, ele não faz apenas uma leitura superficial; ele realiza um parsing real da gramática do Delphi.

Esta é a versão V1, testada exaustivamente contra a base de código do Dext Framework e projetos modernos. No entanto, sabemos que o Delphi tem 29 anos de história e dialetos “exóticos” de código legado que podem surpreender o nosso parser.

Eu preciso da sua ajuda.

Convido você a testar o dext doc no seu projeto. Se o parser engasgar em alguma unit antiga ou sintaxe específica:

1. Não desista.
2. Abra uma Issue no nosso repositório GitHub.
3. Se possível, anexe o trecho de código que causou o erro.

Estou comprometido a evoluir o parser para cobrir o máximo de cenários possíveis. O seu report é o combustível para tornar essa ferramenta robusta para toda a comunidade.

---

Links e Recursos

• Repositório Dext: github.com/cesarliws/dext
• Documentação de API (Gerada com dext doc): Dext API Docs
• Dext Book (Manual Online): Versão PT-BR | English Version
• Livro Delphi Multithreading: cesarromero.com.br/#livros