Criando o Portal de Documentação da sua Aplicação InterSystems IRIS

A linguagem ObjectScript do InterSystems IRIS possui um mecanismo de metadados muito poderoso chamado XData. Este recurso permite criar definições de metadados para as classes úteis para serem utilizadas pelo compilador ou por programas que irão estender as funcionalidades padrão da linguagem baseados nas definições de XData do seu escopo de atuação.

Um exemplo é o IRIS Publisher, uma aplicação Open Source da comunidade capaz de coletar todas as definições de XData no formato HTML e/ou Markdown e gerar um Portal Web com toda a documentação da aplicação montada a partir destes elementos XData.

Veja aqui todo o processo:

Vamos ver um exemplo prático, siga os passos:

1. Acesse o link https://openexchange.intersystems.com/package/IRIS-Publisher para realizar o download do IRIS Publisher.
2. Realize a clonagem do repositório do projeto no git em pasta local da sua escolha: 

   git clone https://github.com/yurimarx/iris-publisher

3. Abra o código fonte do projeto. Ele se encontra na pasta iris-publisher. Iremos criar alguns elementos XData.
4. Vá na classe Person dentro de src/dc/Sample. Inspecione as duas definições de XData de exemplo entre as linhas 34 a 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>

   }
5. São 3 grandes blocos, o texto depois do ///, onde é possível escrever uma descrição do elemento XData; a própria definição do XData e o MimeType (somente HTML e Markdown são capturados) e finalmente, entre {}, todo o conteúdo HTML ou Markdown que irá compor sua documentação. Neste exemplo usamos os dois, mas recomendamos definir apenas 1 deles.
6. É possível anotar todas as classes do projeto, ou parte delas com XData, criando uma documentação bem completa da sua aplicação.
7. Após documentar suas classes utilizando XData, vamos compilar a documentação do projeto, no terminal, execute:

   docker-compose up -d --build

8. Veja o prompt:
9. Após a execução sua instância estará no ar e será possível executar a API do IRIS Publisher.
10. Execute http://localhost:52773/swagger-ui/index.html?url=http://localhost:52773/api/mgmnt/v1/USER/spec/crud#/default/UpdateDocConfig para definir título, informações de desenvolvedor e descrever sua aplicação, utilize o conteúdo a seguir como exemplo:

    {
    "SiteName":"SeuSite",
    "Summary":"Resumo do meu app",
    "Description":"Sobre meu app",
    "DeveloperName":"Seu nome",
    "DeveloperEmail": "seunome@gmail.com",
    "DeveloperWebsite": "seusite.com"
    }

11.   Execute http://localhost:52773/swagger-ui/index.html?url=http://localhost:52773/api/mgmnt/v1/USER/spec/crud#/default/InitiatePublisher para gerar a documentação e iniciar o Portal de Documentação da sua aplicação.
12. Acesse http://localhost:8000 e veja toda a documentação no ar!
13. Tela inicial: