Documentação
Visão Geral
Uma das etapas do ciclo de vida de desenvolvimento de integrações consiste em disponibilizar uma documentação do serviço. Essa documentação pode ser tanto para os consumidores do serviço de integração quanto para os próprios desenvolvedores da integração, para fins de registro de regras de negócio e decisões de design do fluxo.
A documentação de um serviço de integração é composta de uma documentação em formato Markdown. Uma vez criada e devidamente versionada, essa documentação pode ser publicada em um portal. Para saber mais sobre o processo de publicação de integrações no portal, acesse a seção Publicação Dev Portal da integração.
Versionamento da documentação
O DHuO adota um modelo de versionamento automático de documentação, baseado no padrão de versionamento semântico. Neste contexto, existem dois tipos de documentação: a documentação base e a documentação versionada.
A documentação base diz respeito ao conteúdo mais recente da documentação. Ela serve como um rascunho. A partir da versão base, é possível criar versões da documentação e publicar em portais. A ação Salvar salva o conteúdo em rascunho, enquanto a ação Versionar salva o conteúdo (caso modificado) e gera uma versão estável da documentação a partir dele.
A documentação versionada diz respeito ao conteúdo de uma documentação estável e pronta para ser disponibilizada em um portal. A documentação versionada pode ter seu conteúdo atualizado, através da ação Salvar, desde que não esteja publicada em um portal.
As versões seguem o formato vmajor.minor.patch, onde:
- major corresponde ao dígito major da versão da Integração
- minor representa a criação de versões derivadas da documentação base. A cada nova versão criada a partir da versão base (pela ação
Versionar), esse dígito é incrementado - patch representa a criação de versões geradas a partir de uma versão já publicada em um portal
A criação de novas versões de uma documentação ocorre apenas a partir da versão base.
Não é possível editar o conteúdo de uma versão caso ela esteja publicada em algum portal. Ao salvar, será criada uma nova versão, segundo as regras de versionamento. Caso não deseje criar uma nova versão, é possível remover a publicação dos portais, editá-la e publicá-la novamente.
Configuração
A documentação de uma integração é gerenciada pela interface do estúdio da integração. A partir da home, acesse o menu > Integrações. Na página de integrações, visualize a integração desejada e acesse o menu > Documentação.
Na página principal, Documentação, ela pode ser editada e versionada. Por padrão, o conteúdo da documentação base será exibido ao acessar a página.
Na página Histórico de versões as versões existentes da documentação podem ser acessadas e excluídas. Caso deseje visualizar o conteúdo de uma versão específica, acesse a lista de versões e abra a versão desejada.
Não é possível excluir uma versão de documentação caso ela esteja publicada em algum portal. É necessário remover a publicação de todos os portais para excluir uma versão de documentação.
Permissões
Apenas usuários com papel de administrador da organização (Org Admin) ou provedor de APIs (API Provider) podem alterar o conteúdo da documentação. Para saber mais, acesse a seção Papéis e permissões.
Parâmetros
Aqui estão os parâmetros para a criação de uma documentação de integração:
- Conteúdo: Conteúdo da documentação, em formato Markdown.