Documentação
Visão Geral
Uma das etapas do ciclo de vida de desenvolvimento de APIs consiste em disponibilizar uma documentação da API. A especificação da API é sua principal documentação, mas o DHuO fornece uma documentação complementar, menos técnica e independente da estrutura e conceitos de OpenAPI. Essa documentação pode ser tanto para os consumidores da API quanto para os próprios desenvolvedores dela, para fins de registro de regras de negócio e decisões de design do fluxo.
A documentação complementar da API é composta de uma documentação em formato Markdown. Uma vez criada e devidamente versionada, essa documentação pode ser publicada em um portal, juntamente com a especificação da API. Para saber mais sobre o processo de publicação de APIs no portal, acesse a seção Publicação Dev Portal da API.
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 API
- 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 API é gerenciada pela interface do estúdio da API. A partir da home, acesse o menu > APIs. Na página de APIs, visualize a API 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 API:
- Conteúdo: Conteúdo da documentação, em formato Markdown.