Visão geral

Além dos repositórios das aplicações, todo projeto na plataforma Embrapa I/O pode ativar dois repositórios de suporte voltados à documentação pública, como apresentado na criação do projeto:

  • io-web — o site de documentação do projeto, um site estático em Jekyll com o tema Just the Docs, publicado em https://docs.embrapa.io/<projeto>/; e
  • io-api — a documentação da API REST, um arquivo api.json no padrão OpenAPI 3 renderizado com o Swagger UI, publicado em https://api.embrapa.io/<projeto>/.

Os dois são ativados na dashboard, pelo card do projeto, na opção de repositórios de suporte. Cada um nasce como um fork de um boilerplate da plataforma (io/support/web e io/support/api) criado pelo autômato Genesis no grupo do projeto no GitLab. O fluxo de trabalho é o mesmo para ambos: clonar, editar, testar em ambiente local com Docker e fazer push na branch main. Não há pipeline para configurar nem servidor para administrar — a publicação é automática.

Atenção! Tudo o que estiver na main desses repositórios é público. Não versione credenciais, endereços internos ou dados pessoais. Documentação privada do projeto pertence ao repositório io-doc, descrito no capítulo de projeto.

Manter essa documentação atualizada é uma das orientações da plataforma para a sustentação dos ativos digitais.

Site de documentação (Jekyll)

Ativando e clonando

Ative o repositório io-web no card do projeto e aguarde alguns minutos até que o Genesis o crie no GitLab. Em seguida, clone-o:

git clone git@git.embrapa.io:<projeto>/io-web.git
cd io-web

Estrutura do repositório

Caminho Papel
_config.yml Título, descrição, rodapé, callouts e demais opções do tema.
index.md Página inicial do site.
docs/index.md Raiz da seção “Documentação” (has_children: true).
docs/*.md Um arquivo por página, com title, nav_order e parent no front matter.
_includes/head_custom.html Integração com o Matomo (estatísticas de acesso) e carga do WebMCP. Raramente precisa ser editado.
images/ Imagens referenciadas pelas páginas.
Gemfile Dependências Ruby usadas no build.

Atenção! Não defina url nem baseurl no _config.yml. A plataforma injeta os dois valores no momento do build, de acordo com o endereço em que o site é publicado. Defini-los à mão quebra os links e os assets do site publicado.

Escrevendo páginas

Crie um arquivo em docs/ com o front matter do Just the Docs:

---
layout: default
title: Instalação
parent: Documentação
nav_order: 3
---

O conteúdo é Markdown processado pelo Kramdown. O tema traz busca automática em todo o conteúdo, alternância entre tema claro e escuro, âncoras nos títulos e três callouts prontos, aplicados com um atributo logo após o parágrafo:

Este recurso está em fase de testes.
{: .note }

Faça _backup_ antes de executar o comando.
{: .warning }

A variável precisa ser definida antes do primeiro _deploy_.
{: .important }

Diagramas em Mermaid funcionam em blocos de código com a linguagem mermaid. Se uma página precisar de mais níveis, use has_children: true nela e aponte as filhas com parent.

O site também expõe, sem configuração adicional, um conjunto de ferramentas WebMCP para agentes de IA que navegam pela documentação — o mesmo mecanismo descrito no capítulo de WebMCP deste site.

Testando em ambiente local

Com o Docker, na raiz do repositório (o mesmo comando está no README.md):

docker run --rm -it -p 4000:4000 -v "$(pwd):/srv/jekyll" \
  -v <projeto>_gems:/gems -e BUNDLE_PATH=/gems jekyll/jekyll:4.4.1 \
  sh -c 'bundle install && bundle exec jekyll serve -H 0.0.0.0 --force_polling'

Acesse http://localhost:4000. A imagem é a mesma usada na publicação e roda em amd64 e arm64. O --force_polling faz o servidor recompilar a cada arquivo salvo, e o volume <projeto>_gems guarda as gems entre execuções (só a primeira leva cerca de um minuto). Nada é instalado na sua máquina: Ruby, Bundler e as gems vivem dentro do Docker.

Publicando

Faça commit e push na main. Em poucos minutos o site é reconstruído e publicado em https://docs.embrapa.io/<projeto>/, e passa a aparecer no catálogo de docs.embrapa.io assim que o repositório tiver commits próprios além do fork inicial.

Erros comuns

  • Página não aparece no menu: falta parent ou nav_order no front matter, ou o title do pai não coincide exatamente.
  • Build quebra com gem ausente (csv, logger, base64, bigdecimal): o Ruby moderno deixou de embutir essas bibliotecas. Mantenha-as declaradas no Gemfile, como vêm no boilerplate; não as remova.
  • Gemfile.lock gerado na sua máquina: não o versione. Ele é gerado dentro do contêiner e um lock produzido com outro Bundler pode derrubar o build publicado.
  • Links quebrados só em produção: quase sempre é url/baseurl definidos no _config.yml ou caminhos absolutos começando por /. Use {{ site.baseurl }}/caminho nos links internos.

Documentação da API (Swagger)

Ativando e clonando

Ative o repositório io-api no card do projeto, como descrito na criação do projeto, e clone-o:

git clone git@git.embrapa.io:<projeto>/io-api.git
cd io-api

Estrutura do repositório

O repositório é mínimo: api.json (a especificação OpenAPI 3, que é o que importa), config.json (título, descrição e versão de reserva, opcional) e README.md.

Escrevendo a especificação

Edite o api.json em OpenAPI 3.0. Os campos que fazem diferença na página publicada:

  • info.title, info.description e info.version — cabeçalho da documentação;
  • servers — um item por estágio da aplicação, para que o “Try it out” do Swagger UI aponte para a build certa:
"servers": [
  { "url": "https://<projeto>.alpha.agro.rocks/api", "description": "Alpha" },
  { "url": "https://<projeto>.beta.agro.rocks/api", "description": "Beta" },
  { "url": "https://<projeto>.com.br/api", "description": "Produção" }
]
  • paths — cada endpoint com summary, description, tags e operationId. O catálogo de api.embrapa.io usa exatamente esses campos para a busca por endpoint entre todas as APIs da plataforma; endpoints sem summary ficam invisíveis na busca.

Valide o arquivo no Swagger Editor antes de publicar: um arquivo inválido não é publicado, e a versão anterior continua no ar. O api.json também é aceito em YAML; a plataforma o converte e publica em JSON.

Para exibir um ícone no card do projeto no catálogo, coloque um icon.png (ou icon.svg, logo.png, logo.svg) na raiz do repositório.

Testando em ambiente local

Com o Docker, na raiz do repositório (o mesmo comando está no README.md):

docker run --rm -it -p 8000:8080 -v "$(pwd):/api" \
  -e SWAGGER_JSON=/api/api.json swaggerapi/swagger-ui:v5.33.0

Acesse http://localhost:8000. A imagem usa a mesma versão do Swagger UI da publicação e roda em amd64 e arm64. Como o diretório é montado, basta recarregar a página para ver as alterações no api.json.

Publicando

Commit e push na main. A documentação é atualizada em https://api.embrapa.io/<projeto>/ em poucos minutos e entra no catálogo de api.embrapa.io quando o repositório tiver commits próprios.

Erros comuns

  • Página em branco ou erro de parse: vírgula sobrando ou aspas erradas no api.json. O Swagger Editor aponta a linha.
  • “Try it out” falha por CORS: a API precisa responder aos cabeçalhos Access-Control-Allow-Origin para a origem https://api.embrapa.io.
  • Versão errada no cabeçalho: info.version do api.json prevalece sobre o config.json.

Uma especificação OpenAPI bem descrita também serve de base para expor a API a agentes de IA por meio de um MCP Server.

Estatísticas de acesso

As visitas ao site de documentação e à documentação da API são registradas no Matomo da plataforma, em hit.embrapa.io. Não é preciso configurar nada:

  • Ao criar o io-web e o io-api, o Genesis cria no Matomo um site para cada um, no grupo do projeto, com os nomes io-web e io-api.
  • No io-web, o código de rastreamento fica no _includes/head_custom.html, já com o ID do site. Não o remova: sem ele, as visitas deixam de ser contadas.
  • No io-api, a plataforma insere o código de rastreamento na página que publica; o repositório não precisa ter nada.
  • Só contam as visitas ao endereço publicado (https://docs.embrapa.io/<projeto>/ ou https://api.embrapa.io/<projeto>/). Acessos em ambiente local não entram nas estatísticas.

As estatísticas são públicas: qualquer pessoa abre o painel, sem login. O link está no README.md de cada repositório e segue o formato abaixo, em que <ID> é o número do site no Matomo:

https://hit.embrapa.io/index.php?module=CoreHome&action=index&idSite=<ID>&period=day&date=yesterday#?idSite=<ID>&period=day&date=yesterday&category=Dashboard_Dashboard&subcategory=1

Em repositórios mais antigos, cujo README.md não traz o link, o ID aparece no código-fonte de qualquer página publicada, em setSiteId. Os membros da equipe do projeto também têm acesso com login, conforme o papel no GitLab: mantenedores como administradores do site e desenvolvedores com permissão de escrita. Quem ainda não tem conta no Matomo recebe um convite por e-mail.

Como a publicação funciona

A publicação é automática e estática. A cada ciclo de cinco minutos a plataforma verifica a main de cada io-web e io-api, reconstrói o que mudou e serve os arquivos gerados nos domínios docs.embrapa.io e api.embrapa.io, cada um com um site-mãe que cataloga todos os projetos e, no caso das APIs, permite buscar por endpoint.

Três comportamentos valem a pena conhecer:

  • Um build com erro não derruba a versão anterior. O site publicado continua no ar com o último build bem-sucedido. Os mantenedores do projeto no GitLab (papéis Maintainer e Owner) recebem por e-mail o erro, as últimas linhas do registro do build e o link para testar em ambiente local — um aviso por commit que falhou. A falha também fica registrada para a equipe da plataforma.
  • Sites ainda “no modelo” ficam ocultos no catálogo. Enquanto o repositório só tiver o commit do fork, o site continua acessível pelo link direto, mas não é listado no site-mãe — o catálogo mostra apenas projetos que de fato escreveram algo.
  • Não há configuração de servidor. Se o site precisa de uma gem ou de um plugin que não está no Gemfile do boilerplate, o caminho é propor a melhoria no boilerplate, e não ajustar o servidor.