Publicação Dev Portal
Visão Geral
Após a criação da documentação de uma API, representada por sua especificação e documentação Markdown, o próximo passo é disponibilizá-la em um Dev Portal para consumo. O processo de disponibilização de documentação no Dev Portal é chamado de publicação. Uma vez publicada, a documentação estará acessível no menu > Catálogo de APIs do portal. Para saber mais sobre a visualização do catálogo no portal, acesse a seção Catálogo de APIs do Dev Portal.
O Dev Portal atua como catálogo centralizador de documentações de toda a organização. Nele, essa documentação pode ser acessada tanto pelos consumidores da API quanto pelos próprios desenvolvedores dela, para fins de registro de regras de negócio e decisões de design.
Devido à natureza multi-portal do DHuO, é possível publicar uma documentação em vários portais, bem como ter versões diferentes de uma documentação em cada portal.
A visão do catálogo de todas as documentações de APIs publicadas em um portal está disponível no estúdio do portal, pela administração de portais. Para saber mais sobre o catálogo do Dev Portal, acesse a seção Catálogo da Administração do Dev Portal.
Configuração
A publicação de documentações é 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 > Publicação. Na página de publicações, as documentações podem ser adicionadas, atualizadas ou removidas dos portais.
O processo de publicação de documentações de API é dividido em duas etapas:
- publicação da especificação. Essa etapa é obrigatória.
- publicação da documentação Markdown. Essa etapa é opcional.
A publicação envolve a escolha de um portal e uma versão da documentação. Escolha o portal em que a documentação será publicada, selecione a versão da documentação, compare, revise as alterações e realize a publicação.
Para que a opção de publicação de documentação Markdown esteja habilitada, é necessário que a especificação da API correspondente esteja publicada.
Para publicar, é necessário ter versionado a especificação e a documentação Markdown. Para saber mais sobre a criação e versionamento de documentações, acesse as seções Especificação de API e Documentação da API.
Permissões
Apenas usuários com papel de administrador da organização (Org Admin) ou provedor de APIs (API Provider) podem publicar documentações em portais. Para saber mais, acesse a seção Papéis e permissões.
Parâmetros publicação especificação
Aqui estão os parâmetros para a publicação de uma especificação no portal:
- Portal: Obrigatório. Portal onde a especificação será disponibilizada.
- Versão da especificação: Obrigatório. Versão da especificação a ser publicada no portal.
Ao excluir a publicação de uma especificação de um portal, os usuários do portal deixarão de ter acesso a ela. Caso haja documentação Markdown associada, ela também será excluída.
Parâmetros publicação documentação Markdown
Aqui estão os parâmetros para a publicação de uma documentação no portal:
- Portal: Obrigatório. Portal onde a documentação será disponibilizada.
- Versão da documentação: Obrigatório. Versão da documentação a ser publicada no portal.
Ao excluir a publicação de uma documentação de um portal, os usuários do portal deixarão de ter acesso a ela.