El Fin de la Documentación Desactualizada en Delphi: Swagger & Dext Doc

“Código sin documentación es código temporal.” Esta máxima guía el desarrollo de Dext Framework desde su concepción. Pero seamos honestos: mantener la documentación actualizada es una de las tareas más ingratas del desarrollo.

Quien haya trabajado en proyectos largos conoce el ciclo: creas la API, escribes un hermoso PDF o Wiki, y dos semanas después… la documentación ya es mentira. Un parámetro cambió, surgió un nuevo endpoint y el documento quedó olvidado en el cajón.

Dext Framework resuelve este problema atacando la causa raíz: La documentación no debe ser un artefacto separado; debe nacer del propio código.

En este artículo, presento las dos herramientas nativas de Dext que automatizan este proceso: Swagger/OpenAPI (para quienes consumen su API) y dext doc (para quienes mantienen su código).

---

1. Swagger/OpenAPI: Su API Documentada en Tiempo Real

La mejor documentación es aquella que no necesita abrir Word para escribirla. Dext brinda soporte de primera clase al estándar OpenAPI, permitiendo que la especificación de su API viva junto con la implementación.

No es un “add-on” o componente de terceros. Es nativo.

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

App.Configure(procedure(App: IApplicationBuilder)
begin
  // Una línea y su documentación interactiva está en el aire
  App.UseSwagger;

  // Sus endpoints aquí...
end);

La Magia de la API Fluida

Olvídese de archivos XML complejos o comentarios gigantescos que contaminan el código. Dext utiliza una DSL (Domain Specific Language) fluida y atributos modernos. Usted documenta la intención del endpoint en el momento en que lo define:

SwaggerEndpoint.From(App.MapGet('/api/users/{id}', GetUserHandler))
  .Summary('Buscar usuario por ID')
  .Description('Retorna los detalles completos del usuario.')
  .Tag('Usuarios')
  .Response(200, TypeInfo(TUser), 'Usuario encontrado')
  .Response(404, TypeInfo(TErrorResponse), 'Usuario no encontrado');

¿El resultado? Si cambia el tipo de retorno en el código, Swagger refleja el cambio de inmediato. La documentación nunca se desincroniza.

Schemas Inteligentes con Atributos

Para sus DTOs y entidades, utilizamos atributos que enriquecen la documentación visual:

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

    [SwaggerProperty('Email corporativo')]
    [SwaggerFormat('email')] // Validación visual en Swagger UI
    Email: string;
  end;

---

2. dext doc: La Herramienta que Delphi Merecía

Durante el desarrollo de Dext, tenía un requisito innegociable: la documentación interna de la API (clases, units, arquitectura) debía ser impecable y automática. Intenté usar las herramientas Open Source disponibles en el mercado… y me frustré.

Algunas no entendían las sintaxis modernas (como Generics avanzados o Atributos), otras generaban un HTML con un aspecto anticuado y la mayoría fallaba al intentar analizar la complejidad del código del framework.

Me di cuenta de que si quería calidad, tendría que construirla. Así nació dext doc.

dext doc resultó tan bueno que trascendió al propio framework. Hoy, es una poderosa herramienta standalone que puede usarse en cualquier proyecto Delphi, ya sea que use Dext Framework o no.

¿Por qué es diferente?

A diferencia de los generadores basados solo en comentarios XML, dext doc realiza un análisis profundo de la AST (Árbol de Sintaxis Abstracta) de su código.

• Entiende Delphi Moderno: Generics, Anonymous Methods, Attributes — lo lee todo de forma nativa.
• Diagramas Automáticos (Mermaid): No solo enumera métodos; dibuja la arquitectura. Cada clase obtiene un diagrama UML generado al instante, mostrando herencias e interfaces.
• Configuración Cero: No es necesario instalar Node.js, Java, Graphviz o dependencias oscuras. Es un ejecutable simple: apuntar, generar.

Éxito con Semantic XML

Además del análisis estadístico, dext doc respeta el estándar de Semantic XML Comments. Esto significa que puede enriquecer su documentación técnica con descripciones detalladas, parámetros y retornos utilizando la misma sintaxis que el propio Delphi utiliza para 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;

Su Puerta de Entrada a lo Moderno

Tal vez no pueda migrar su ERP heredado a la arquitectura de Dext hoy. Pero puede comenzar a documentarlo con la calidad de Dext ahora mismo.

Ejecute el comando en la carpeta de su proyecto actual:

dext doc --input ./SuProyectoHeredado --output ./Docs --title "Documentación ERP"

Y vea cómo su código cobra vida en un sitio moderno, responsivo, con búsqueda instantánea y Modo Oscuro. Es la forma más segura e inmediata de elevar el nivel profesional de su proyecto.

---

3. Workflow Integrado: La Cultura de la Documentación

La filosofía de Dext no es solo proporcionar clases útiles, es elevar el listón de la ingeniería de software en el ecosistema Delphi.

Al adoptar estas herramientas, cambia la cultura del equipo:

1. En el Pull Request: El revisor verifica si los atributos [Swagger] están claros.
2. En CI/CD: El pipeline ejecuta dext doc y publica la nueva versión del sitio automáticamente.
3. En el Onboarding: El nuevo desarrollador recibe el enlace de la documentación y puede navegar visualmente por la arquitectura.

Conclusión

La documentación no tiene por qué ser burocracia. Cuando la herramienta adecuada trabaja para usted, documentar se convierte en una consecuencia natural de escribir un buen código.

Pruebe a ejecutar dext doc en su proyecto hoy y vea su arquitectura con otros ojos.

---

🚧 Nota de Transparencia: El Desafío del Parser

dext doc es una herramienta ambiciosa. Para generar diagramas y una documentación rica, no solo hace una lectura superficial; realiza un parsing real de la gramática de Delphi.

Esta es la versión V1, probada exhaustivamente contra la base de código de Dext Framework y proyectos modernos. Sin embargo, sabemos que Delphi tiene 29 años de historia y dialectos “exóticos” de código heredado que pueden sorprender a nuestro parser.

Necesito su ayuda.

Le invito a probar dext doc en su proyecto. Si el parser se atraganta con alguna unidad antigua o sintaxis específica:

1. No se rinda.
2. Abra un Issue en nuestro repositorio de GitHub.
3. Si es posible, adjunte el fragmento de código que causó el error.

Me comprometo a evolucionar el parser para cubrir tantos escenarios como sea posible. Su reporte es el combustible para hacer que esta herramienta sea robusta para toda la comunidad.

---

Enlaces y Recursos

• Repositorio Dext: github.com/cesarliws/dext
• Documentación de API (Generada con dext doc): Dext API Docs
• Dext Book (Manual Online): English Version | PT-BR Version
• Libro Delphi Multithreading: cesarromero.com.br/#livros