Swagger Editor

O Editor do Swagger é utilizado para editar o design da API fazendo uso da estrutura YAML ou JSON. O acesso ao editor fica localizado no card da API em API Catalog, por meio do ícone que é o logo oficial do Swagger:

Não acesse o editor do Swagger por outro caminho que não seja clicando no ícone do Swagger (por exemplo, abrindo mais de uma aba ou janela no navegador). Isso acarretará no mal funcionamento do editor.

Realizando alterações na API

Durante a edição do design da API, o editor monitora os possíveis erros de acordo com a estrutura padrão do Swagger e os exibe na tela de preview localizado ao lado direito.

Se houver algum erro, os botões SAVE e SAVE AS NEW REVISION ficarão desabilitados, ou seja, não será possível salvar as alterações até que os erros indicados sejam corrigidos.

A imagem abaixo exibe um erro relacionado ao host: ele não contém um base path (o correto seria a inserção de um valor, como "/petstore/v3"). Em caso de dúvidas sobre a especificação do Swagger, acesse esta página).

O editor contém todas as informações relacionadas à API. Quando essas informações são salvas, o Manager armazena o conteúdo do editor e atualiza as informações básicas dos resources e operations dentro do sistema.

Pelo editor do Swagger da API, também é possível fazer download do arquivo Swagger, gerar um servidor e gerar um cliente.

O host definido no editor não impacta no cadastro da API no Manager, ou seja, ele apenas diz respeito ao arquivo do Swagger, o restante do conteúdo é o mesmo da API. O cadastro de API suporta múltiplas URLs, tanto para produção quanto para sandbox, e por isso os hosts são tratados de forma independente.

Cenário de erro

Editor A e B exibindo a mesma API

O usuário faz alterações no editor A e salva as informações com sucesso; posteriormente, o mesmo usuário faz alterações no editor B. Consequentemente, as informações da API são sobrescritas.

Salvando as alterações

Há duas opções para salvar as alterações realizadas no editor, localizadas no canto superior direito da tela:

SAVE: permite salvar as alterações realizadas sobrescrevendo a revisão atual da API, ou seja, sem gerar uma nova revisão.
SAVE AS NEW REVISION: salva as alterações criando uma nova revisão para a API.

Após salvar o Swagger, o usuário é redirecionado para a tela de sucesso no Manager, onde é possível criar um plano ou fazer o download do Swagger da API.

Tenha cuidado ao salvar na mesma revisão as alterações realizadas. Se houver algum erro na alteração, uma API implantada em produção pode ser impactada negativamente, resultando em falhas ou interrupções no serviço. Certifique-se de revisar cuidadosamente todas as alterações antes de salvá-las na mesma revisão.
Lembre que os hosts de download do Swagger no Manager e no editor não possuem ligação, a não ser que ambos estejam cadastrados com o mesmo domínio.

Em caso de erro ao salvar a API, uma mensagem será exibida no preview do editor. Na imagem abaixo, por exemplo, a mensagem de erro foi gerada por falta de um recurso que foi cadastrado no Manager, mas não está presente no documento Swagger.

Download do arquivo Swagger

É possível fazer download do arquivo Swagger da API em dois formatos: YAML ou JSON. Para isso, clique no botão File e escolha entre Save as YAML ou Convert and save as JSON.

Geração de servidor

Em Generate Server, é possível gerar a estrutura básica de um servidor para exposição da API.

Geração de client/SDKs

Clicando em Generate Client, você pode gerar uma SDK em diversas linguagens para consumir os recursos da API, acelerando assim o processo de desenvolvimento.

Thanks for your feedback!

EDIT

Share your suggestions with us!
Click here and then [+ Submit idea]