Os sites de documentação e as documentações de API dos projetos — os repositórios de suporte io-web e io-api — passaram a ser publicados de uma nova forma. Desde 18 de setembro de 2026, cada site é gerado como arquivos estáticos e servido diretamente, em vez de manter um container rodando para cada projeto. Para quem documenta, o fluxo continua o mesmo: editar, fazer push na branch main e aguardar a publicação, nos mesmos endereços de sempre.

Hoje são 186 sites de documentação em docs.embrapa.io e 168 APIs em api.embrapa.io.

O que muda para quem documenta

  • Publicação em poucos minutos. A plataforma verifica a main de cada repositório a cada 5 minutos, gera o site e o publica. Não há pipeline para configurar.
  • Um build com erro não derruba o site. A versão anterior continua no ar até que a correção seja publicada, e os mantenedores do projeto no GitLab recebem por e-mail o erro e as últimas linhas do registro do build — um aviso por commit. A falha também fica registrada para a equipe da plataforma.
  • Páginas mais rápidas. Servidas como arquivos estáticos, as páginas responderam cerca de seis vezes mais rápido nos testes feitos durante a migração (mediana de 27 ms contra 176 ms).
  • Os endereços não mudaram. https://docs.embrapa.io/<projeto>/ e https://api.embrapa.io/<projeto>/ continuam valendo, com os mesmos caminhos internos; links já publicados seguem funcionando.

Catálogos com busca

A raiz dos dois domínios agora é um catálogo de todos os projetos:

  • Em docs.embrapa.io, a busca percorre o conteúdo de todos os sites de documentação de uma só vez.
  • Em api.embrapa.io, a busca é por endpoint (método, caminho e resumo) em todas as APIs, com link direto para a operação no Swagger UI. Por isso vale caprichar no summary, na description e nas tags de cada endpoint do api.json.
  • Cada card mostra o ícone do próprio projeto — no site de documentação, o favicon do site; na API, um icon.png (ou logo.png, logo.svg) na raiz do repositório.
  • Repositórios que ainda têm apenas o conteúdo do modelo ficam fora do catálogo até o primeiro commit próprio, mas continuam acessíveis pelo link direto.

Estatísticas de acesso públicas

As visitas aos sites de documentação e, agora também, às páginas de API são registradas no Matomo da plataforma. As estatísticas são públicas: o painel abre sem login, e o link de cada projeto vem no README.md do repositório. Os detalhes estão na seção de estatísticas de acesso.

Mais flexibilidade nas APIs

  • O api.json também é aceito em YAML: a plataforma converte e publica em JSON.
  • A página de cada API ganhou uma barra com a marca do Embrapa I/O e o caminho de volta para o catálogo.

Execução local mais simples

Os boilerplates io/support/web e io/support/api passaram a trazer, no README.md, um único comando docker run para ver o site ou a API em ambiente local, com as mesmas imagens usadas na publicação e compatíveis com as arquiteturas amd64 e arm64 (inclusive Macs com Apple Silicon). Os comandos estão também nas seções de site de documentação e de documentação da API.

Para saber mais

O passo a passo completo — ativar, editar, testar e publicar — está no capítulo Repositórios de Suporte. E os sites de documentação e os catálogos também estão prontos para agentes de IA no navegador, como contamos no post sobre o WebMCP.