Artículo
· 3 sep, 2021 Lectura de 3 min

Cómo crear el Portal de Documentación para InterSystems IRIS

El lenguaje ObjectScript de InterSystems IRIS tiene un motor de metadatos muy potente llamado XData. Esta característica permite crear definiciones de metadatos para tus clases, que serán utilizadas por el compilador o por los programas para ampliar las características estándar del lenguaje, basándose en las definiciones XData de su campo de acción.

Un ejemplo es IRIS Publisher, una aplicación de código abierto de la Comunidad, capaz de recopilar todas las definiciones de XData en formato HTML y/o Markdown, y que puede generar un Portal web con todos los documentos de la aplicación, recopilados a partir de estos elementos XData.

Aquí puedes ver todo el proceso:

El Publicador de IRIS en acción

Vamos a ver un ejemplo práctico. Sigue estos pasos:

  1. Accede al enlace https://openexchange.intersystems.com/package/IRIS-Publisher para descargar IRIS Publisher
  2. Clona el repositorio del proyecto en git en una carpeta local de tu elección: git clone https://github.com/yurimarx/iris-publisher
  3. Abre el código fuente del proyecto. Está en la carpeta iris-publisher. Con él vamos a crear algunos elementos XData
  4. Ve a la clase Person dentro de src/dc/Sample. Inspecciona las dos definiciones de XData de ejemplo que se encuentran entre las líneas 34 y 43
/// Documentation for Person in HTML
XData PersonDocHtml [ MimeType = text/html ]
{
<h1>This is the Person class</h1>
}

 

/// Documentation for Person in Markdown
XData PersonDocMarkdown [ MimeType = text/markdown ]
{
<h1>This is the Person class in MD</h1>
}
  1. Hay 3 bloques grandes: el texto después de ///, donde es posible escribir una descripción del elemento XData; la propia definición de XData y MimeType (solo se capturan HTML y Markdown); y, finalmente, entre {}, todo el contenido HTML o Markdown que compondrá tu documentación. En este ejemplo utilizamos ambos, pero recomendamos definir solo uno de ellos
  2. Es posible anotar todas las clases del proyecto, o parte de ellas, con XData, para crear una documentación muy completa de tu aplicación
  3. Después de documentar tus clases usando XData, vamos a compilar los documentos del proyecto en el terminal. Ejecuta: docker-compose up -d --build
  4. Después de la ejecución, tu instancia estará activa y podrás ejecutar la API de IRIS Publisher
  5. Ejecuta http://localhost:52773/swagger-ui/index.html?Url=http://localhost:52773/api/mgmnt/v1/USER/spec/crud#/default/UpdateDocConfig para definir el título, la información del desarrollador y describir tu aplicación. Utiliza el siguiente contenido como ejemplo:
{
"SiteName":"Publisher",
"Summary":"Documentation of the Publisher",
"Description":"This an Application to generate documentation from XDATA",
"DeveloperName":"Yuri Gomes",
"DeveloperEmail": "yurimarx@gmail.com",
"DeveloperWebsite": "ymservices.tech"
}

  1. Ejecuta http://localhost:52773/swagger-ui/index.html?url=http://localhost:52773/api/mgmnt/v1/USER/spec/crud#/default/InitiatePublisher para generar la documentación e iniciar el Portal de Documentos para tu aplicación
  2. ¡Ve a http: // localhost: 8000 y consulta toda la documentación on line!

Comentarios (0)2
Inicie sesión o regístrese para continuar