Redocumentando a API do SIORG com Swagger

O SIORG é um dos sistemas estruturantes da APF. Na verdade ele é visto como o Estruturante dos Estruturantes, título dado em virtude do papel central que ele desempenha. Ele é responsável pela gestão da estrutura organizacional de toda a APF. Ou seja, é através da organização dos seus dados que hoje conseguimos cruzar os dados dos outros sistemas estruturantes, o SIAFI, o SIOP, o SIGEPE e do SIASG.

Para acesso aos dados, o Siorg disponibiliza uma API (http://estruturaorganizacional.dados.gov.br/) que permite consultas em XML, CSV e JSON. A documentação completa da API pode ser acessada aqui.

Como você deve ter notado a documentação é um arquivo PDF. Apesar da API implementar várias funcionalidades bem interessantes, a falta de uma documentação mais simples e interativa dificulta sua compreensão e, consequentemente, a disseminação e utilização dos dados. :thinking:

Sem mais delongas, pelos motivos apresentados decidimos reescrever a documentação seguindo o padrão Swagger. Ele é um padrão de descrição de API (similar ao WSDL dos web services Soap) que se estabeleceu como referência e possibilitou o surgimento de uma infinidade de bibliotecas, frameworks e serviços complementares. No governo algumas APIs já utilizam este padrão:

Como disse, uma das principais vantagens do padrão swagger é a diversidade de tecnologias prontas e abertas. Se vc percebeu a semelhança entre as APIs exemplificadas é pelo fato de terem reutilizado uma interface pronta que possibilita visualizar e interagir com a API. Além disso também existe um editor online para criação da documentação, que na verdade é persistida em um arquivo YML.

Voltando ao SIORG, após uma análise rápida concluímos ser totalmente possível migrar o formato da documentação do PDF para o Swagger! :partying_face:

Daí pra frente seguimos reescrevendo. Após pouco mais de 3 dias nessa atividade chegamos a uma versão preliminar:

O projeto está versionado no Github em https://github.com/economiagovbr/Siorg-API-doc.

Os próximos passos serão:

  1. Melhorar os textos e descrições dos métodos da API
  2. Aplicar um estilo CSS mais “interessante”
  3. Publicar uma versão preliminar no Github Pages (zero burocracia)
  4. Substituir o PDF pela nova documentação!

Este projeto nos fez pensar em outros experimentos possíveis:

  1. Desenvolver uma nova interface de navegação nos dados do Siorg utilizando VueJS
  2. Automatizar testes da API para verificar sua saúde
  3. Desenvolver uma extensão da API incluindo métodos mais específicos (listar Autarquias, listar Colegiados, listar Empresas públicas, listar Vinculações, etc…)

Way to Go!

2 Curtidas

Que legal @nitai !
Outro exemplo é a API do Portal de Serviços:
https://www.servicos.gov.br/api/v1/docs#

2 Curtidas

tenho interesse! alguém já tem uma ideia de arquitetura!
React e Vue nois manja. para swagger talvez com nodejs seria mais facil ja tem varios packs no npm prontos so teriamos que chamar as URI’s novamente. nesse caso teria um outro container rodando e chamando o wsld. tem que ver o que é mais vantajoso.
a disposição

Opa, legal, @priminho. O App em Vue é uma das possíveis continuidades desse projetinho, mas não é minha prioridade nesse momento. Bom saber que vc conhece Vue e tem interesse. Além desse temos outros experimentos rolando agora, como a montagem e manutenção do Ecodados (este fórum). E no Siorg eu tô mais interessado nesse momento na outra ideia, de desenvolver uma extensão da API pra criar novos métodos. Eu acho que isso vai simplificar o entendimento e tb pode dar pistas/ideias conceituais de como seria o App em Vue. Essa “extensão” da API na verdade seria tipo um proxy/plugin que faz uma consulta na API original já filtrando por tipo e meio que transforma o resultado pra ficar mais simples entender. Como se fosse uma Tipagem dos dados, agregando mais semântica. Poderia ser feito em qualquer linguagem. Nodejs, por exemplo, rodando num container. o/

Excelente trabalho, @nitai!

Minha sugestão para o próximo passo é colocar uma descrição e um README no repositório do projeto no Github. Poderia até reaproveitar o texto que você já escreveu neste post.

Isso me lembrou o projeto publicbodies.org, que participei há algum tempo. É um projeto que visa coletar informações sobre órgãos públicos de países de todo o mundo. Outro projeto mais recente, mas que envolve qualquer tipo de organização, e não só governos, é o org-id.guide.

É necessário atualizar os dados do Public Bodies com os da API do SIORG atual. Se não me engano, ainda está com os dados de 2014. No seu repositório no Github, tem os scripts que utilizei para importar os dados a partir da versão antiga do SIORG.

1 Curtida