A sigla API significa Application Programming Interface, em Português, Interface de Programação de Aplicações. Esta permite a integração de sistemas, apresentando vantagens como a proteção e segurança dos dados, otimização da performance da plataforma, automatização dos processos, facilidade na troca de informação entre sistemas com diferentes linguagens de programação.
Com o Swagger UI é possível criar facilmente uma interface que permite interagir com a sua API. Aprenda como usar.
O Swagger UI é um projeto de código aberto para renderizar visualmente a documentação de uma Application Programming Interface definida com a especificação OpenAPI (Swagger).
A interface Swagger permite que visualize e interaja com os recursos da API, facilitando a implementação de backend e o consumo do lado do cliente.
Como usar o Swagger numa API em Node.js
Para este exemplo vamos considerar uma calculadora. A calculadora deverá receber dois números de entrada e realizar as operações necessárias.
Para este projeto vamos começar por criar um novo repositório no GitHub com o nome calculadora_swagger.
Em seguida vamos copiar o link do repositório para importar no Visual Studio Code.
Já dentro do Visual Studio Code é fazer a importação do repositório. Para isso, basta usar o atalho CTRL + SHIFT + P para abrir a caixa de comandos. Aí dentro escolham a opção Clone depois Clone from GitHub e indiquem o url do repositório.
Devem depois indicar onde se localizará o projeto no vosso sistema de ficheiros. Para finalizar devem também adicionar o projeto ao WorkPlace. Podem ver aqui como fazer.
Vamos começar…
Usando a linha de comandos vamos iniciar o projeto com o comando npm init. Devem depois indicar os parâmetros solicitados.
Em seguida instalamos o Express usando o comando. O Express.js é uma framework para Node.js que permite o desenvolvimento de aplicações Web de uma forma muito simples. A instalação do Express.js no ambiente de programação deve ser feito através do NPM.
npm install express
Em seguida instalamos o swagger-ui
npm i swagger-ui-express -S
Após instalar as dependências, vamos criar o ficheiro index.js e colocar lá o seguinte código:
Em seguida criamos o ficheiro swagger.json. Para este exemplo vamos definir apenas para a operação SOMA.
Por fim, vamos executar o nosso projeto usando o comando.
node index.js
Abram o endereço http://localhost:8001/api-docs/ e deverão ver a seguinte interface.
Para testar se tudo está operacional, carreguem em Try Out, indiquem dois números…
e depois carreguem em Execute. O resultado deverá aparecer no campo Response body.
Como viram não é muito difícil documentar uma API com o Swagger. De referir que é possível usar a linguagem JSON ou então YAML para produzir o ficheiro com a interface. Boas programações.