A Especificação OpenAPI (OAS) define uma descrição de interface padrão, independente de linguagem de programação, para APIs HTTP, o que permite tanto humanos quanto computadores descobrirem e entenderem as capacidades de um serviço sem exigir acesso ao código-fonte, documentação adicional ou inspeção do tráfego de rede. Quando devidamente definida via OpenAPI, um consumidor pode entender e interagir com o serviço remoto apenas configurando alguns parâmetros na tela de importação do serviço. Semelhante ao que as descrições de interface fizeram para programação em níveis mais baixos, a especificação OpenAPI remove a necessidade de adivinhação ao chamar um serviço. Para mais informações, acesse a documentação oficial do OpenAPI Specification.
Importando OpenAPI/Swagger
Acesse o menu Projeto > Importar e na janela que será exibida, escolha a opção OpenAPI/Swagger, por fim, clique em Avançar. como mostra a figura abaixo.
Figura 1 - Importando OpenAPI/Swagger
Configuração
Após selecionar a opção OpenAPI/Swagger, a janela de configuração da funcionalidade será exibida, preencha os campos e clique em Avançar para dar continuidade ao processo.
Figura 2 - Configuração da janela OpenAPI
URL: campo destinado à informar o caminho da API. Ao preencher este campo, os campos das propriedades Url base e Namespace serão preenchidos automaticamente.
URL base: ponto de entrada principal para os recursos disponíveis da API. É a parte fixa da URL que geralmente permanece constante para todas as requisições feitas à API. A URL base, quando combinada com caminhos específicos de recurso, permite que os clientes acessem endpoints específicos da API.
Categoria:
Usar tags como categoria: crua categorias novas de blocos de programação baseadas nas tags da API.
Namespace: campo preenchido automaticamente ao inserir a URL.
Cabeçalhos: os campos de cabeçalho são utilizados para situações em que o usuário precise acessar algum recurso da API que precise de autenticação.
Chave: nome do cabeçalho, por exemplo, "Authorization", "Content-Type", "X-AUTH-TOKEN".
Valor: conteúdo ou o valor atribuído a essa chave
Figura 2.1 - Configuração das tags da API
Exemplos
Para ilustrar, vamos apresentar dois exemplos: inicialmente, vamos desenvolver blocos de programação utilizando uma API, importando-a via OpenAPI/Swagger. Em seguida, criaremos uma fonte de dados para extrair registros específicos dessa API. Ambos os exemplos serão baseados na API PetStore.