Tutorial: Como desenvolver uma API com Node.js e Swagger

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.