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 APIs, cujo seu ícone é o logo oficial do Swagger.

Não é correto acessar 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 fez alterações no editor A e salvou as informações com sucesso, posteriormente o mesmo faz alterações no editor B, consequentemente as informações da API serão sobreescritas.

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.

No exemplo abaixo é exibido um erro relacionado ao host, onde o mesmo não contém um 'basePath', acarretando na exibição da mensagem de erro. O correto seria a inserção de um valor como /ecommerce/v1. Em caso de dúvidas sobre a especificação do Swagger, acesse Swagger Specification.

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 operationsdentro do sistema.

Pelo editor do Swagger da API é possível:

  • Fazer download do Swagger;
  • Configurar opções do editor;
  • Geração de Servidor;
  • Geração de Client/SDKs.

Download Swagger

É possível fazer download do Swagger da API em dois formatos: YAML e JSON.

Configuração

Em Preferences é possível fazer algumas configurações do editor como: tamanho de fonte, tema e identação.

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

Em geração de SDKs é possível 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. Lembrando que o host de download do Swagger no Manager e editor não possuem ligação, ao menos que esteja cadastrado com o mesmo domínio em ambos os locais.

Em caso de erro ao salvar a API, uma mensagem será exibida no preview do editor:

No exemplo acima temos um caso de mensagem de erro gerada por falta de um recurso que foi cadastrado no Manager, mas não está presente no documento Swagger.

Tem mais dúvidas? Envie uma solicitação

Comentários

Powered by Zendesk