Formatação Técnica em Artigos
Este artigo demonstra como criar documentação técnica utilizando os recursos avançados da Base de Conhecimento da TomTicket.
Além da formatação tradicional de textos, títulos, tabelas e listas, também é possível documentar APIs, exemplos de código e estruturas JSON de forma padronizada e interativa.
Como funciona
O editor permite escrever artigos utilizando HTML normalmente. Durante a renderização do artigo, alguns elementos recebem um tratamento especial, tornando a documentação muito mais organizada.
Atualmente existem dois recursos principais:
- Blocos de código com destaque de sintaxe.
- Tabelas automáticas para documentação de JSON de entrada e saída.
Blocos de código
Para inserir um bloco de código, utilize a tag <pre> juntamente com o atributo data-language.
O sistema identifica automaticamente a linguagem e aplica destaque de sintaxe durante a renderização do artigo.
Exemplo:
<pre data-language="PHP">
<?php
echo "Olá Mundo";
$nome = "TomTicket";
echo $nome;
</pre>Linguagens suportadas:
- PHP
- JSON
- Bash
- Curl
- JavaScript
- NodeJS
- TypeScript
- Python
- Java
- SQL
- CSV
- HTML
- XML
- YAML
- Texto
Documentação de APIs
Para documentar estruturas JSON não é necessário criar tabelas manualmente.
Basta inserir um bloco <pre> utilizando a classe tt-json-doc.
Durante a renderização, o conteúdo será automaticamente convertido em uma tabela interativa.
Exemplo de JSON de entrada
Escreva exatamente desta forma:
<pre class="tt-json-doc"
data-kind="request"
data-title="JSON de entrada">
{
"ticket_id": {
"type": "string",
"required": true,
"max_length": 255,
"description": "Identificador do chamado."
}
}
</pre>Resultado:
JSON de entrada
| Campo | Tipo | Obrigatório | Tamanho máximo | Descrição |
|---|---|---|---|---|
ticket_id | string | Sim | 255 | Identificador do chamado. |
Exemplo de JSON de saída
Escreva exatamente desta forma:
<pre class="tt-json-doc"
data-kind="response"
data-title="JSON de saída">
{
"data": {
"type": "object",
"description": "Objeto principal.",
"children": {
"id": {
"type": "string",
"description": "Identificador."
},
"customer": {
"type": "object",
"description": "Dados do cliente.",
"children": {
"name": {
"type": "string",
"description": "Nome do cliente."
}
}
}
}
}
}
</pre>Resultado:
JSON de saída
| Campo | Tipo | Descrição |
|---|---|---|
data | object | Objeto principal. |
id | string | Identificador. |
customer | object | Dados do cliente. |
name | string | Nome do cliente. |
Campos disponíveis
Os seguintes atributos podem ser utilizados na documentação dos campos:
| Campo | Descrição |
|---|---|
| type | Tipo do campo. |
| required | Indica se o campo é obrigatório. |
| max_length | Tamanho máximo permitido. |
| description | Descrição exibida na documentação. |
| children | Campos filhos quando o tipo for object ou array. |
Resultado final
Durante a visualização do artigo, todos os blocos de documentação são convertidos automaticamente em tabelas modernas, permitindo expandir e recolher objetos aninhados.
Essa abordagem facilita a manutenção da documentação, evita edição manual de tabelas HTML e mantém um padrão único para toda a Base de Conhecimento.
Referência da Sintaxe
A documentação técnica da Base de Conhecimento utiliza uma sintaxe própria para geração automática de blocos de código e documentação de APIs.
Blocos de código
Utilize a tag <pre> juntamente com o atributo data-language.
| Atributo | Obrigatório | Descrição | Exemplo |
|---|---|---|---|
| data-language | Sim | Linguagem utilizada para o destaque de sintaxe. | PHP |
Exemplo:
<pre data-language="PHP">
<?php
echo "Olá Mundo";
</pre>Documentação de JSON
Para documentação de entrada ou saída de APIs, utilize um <pre> com a classe tt-json-doc.
| Atributo | Obrigatório | Descrição | Valores |
|---|---|---|---|
| class | Sim | Identifica o bloco como documentação JSON. | tt-json-doc |
| data-kind | Sim | Define se o JSON representa entrada ou saída. | request ou response |
| data-title | Não | Título exibido acima da tabela. | JSON de entrada |
Exemplo:
<pre
class="tt-json-doc"
data-kind="request"
data-title="JSON de entrada"
>
{
...
}
</pre>Estrutura dos campos
| Propriedade | Obrigatória | Descrição |
|---|---|---|
| type | Sim | Tipo do campo. |
| description | Sim | Descrição exibida na documentação. |
| required | Somente request | Define se o campo é obrigatório. |
| max_length | Não | Tamanho máximo permitido. |
| children | Quando aplicável | Lista de propriedades filhas para objetos e arrays. |
Tipos suportados
| Tipo | Descrição |
|---|---|
| string | Texto. |
| integer | Número inteiro. |
| number | Número decimal. |
| boolean | Valor verdadeiro ou falso. |
| object | Objeto contendo propriedades filhas. |
| array | Lista de objetos ou valores. |
| datetime | Data e hora. |
| date | Data. |
| time | Hora. |
Exemplo completo
<pre
class="tt-json-doc"
data-kind="request"
data-title="JSON de entrada"
>
{
"ticket_id": {
"type": "string",
"required": true,
"max_length": 255,
"description": "Identificador do chamado."
},
"customer": {
"type": "object",
"description": "Dados do cliente.",
"children": {
"name": {
"type": "string",
"required": true,
"max_length": 120,
"description": "Nome do cliente."
},
"email": {
"type": "string",
"required": false,
"max_length": 255,
"description": "E-mail."
}
}
}
}
</pre>Durante a renderização do artigo, esse conteúdo será automaticamente convertido em uma tabela interativa com suporte à expansão e contração dos objetos aninhados, preservando toda a estrutura do JSON original.