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.

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 consequentemente sobrescritas.

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.

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.

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 /ecommerce/v1). 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 é possível fazer download do arquivo Swagger, gerar um servidor e gerar um cliente.

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.

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.

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.

Thanks for your feedback!

EDIT

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