10.11. Criando uma API REST básica com NodeJS e ExpressJS: Documentação da API

O NodeJS, juntamente com o ExpressJS, é uma das ferramentas mais populares para a criação de APIs REST. Neste capítulo do nosso e-book, vamos aprender a criar uma API REST básica usando essas tecnologias e também a documentar a API para facilitar o uso por outros desenvolvedores.

1. Configurando o Ambiente

Primeiro, precisamos instalar o NodeJS e o ExpressJS. O NodeJS pode ser baixado e instalado a partir do site oficial. Após a instalação do NodeJS, podemos instalar o ExpressJS usando o gerenciador de pacotes npm, que é instalado junto com o NodeJS. No terminal, execute o seguinte comando:

npm install express --save

2. Criando a Estrutura Básica da API

Em seguida, vamos criar a estrutura básica da nossa API. Primeiro, crie um novo arquivo chamado app.js. Este será o ponto de entrada para a nossa API. Adicione o seguinte código ao arquivo:

const express = require('express');
const app = express();
app.listen(3000, () => {
  console.log('API is running on http://localhost:3000');
});

Este código simplesmente cria um novo servidor ExpressJS que escuta na porta 3000.

3. Adicionando Rotas

As APIs REST são baseadas em rotas, que são URLs que representam diferentes recursos. Vamos adicionar algumas rotas básicas à nossa API. Adicione o seguinte código ao arquivo app.js:

app.get('/', (req, res) => {
  res.send('Welcome to our API!');
});

app.get('/users', (req, res) => {
  res.send('List of users');
});

app.get('/users/:id', (req, res) => {
  res.send(`User with ID ${req.params.id}`);
});

Estas rotas respondem a solicitações GET. A primeira rota responde à URL base (/) com uma mensagem de boas-vindas. A segunda rota responde à URL /users com uma lista fictícia de usuários. A terceira rota responde à URL /users/:id, onde :id é um parâmetro que pode ser qualquer valor. Esta rota retorna um usuário fictício com o ID especificado.

4. Criando um Banco de Dados Fictício

Para tornar a nossa API um pouco mais interessante, vamos criar um banco de dados fictício de usuários. Adicione o seguinte código ao arquivo app.js:

const users = [
  { id: 1, name: 'Alice' },
  { id: 2, name: 'Bob' },
  { id: 3, name: 'Charlie' }
];

app.get('/users', (req, res) => {
  res.send(users);
});

app.get('/users/:id', (req, res) => {
  const user = users.find(u => u.id === parseInt(req.params.id));
  if (!user) res.status(404).send('User not found');
  else res.send(user);
});

Agora, a rota /users retorna a lista de usuários do nosso banco de dados fictício, e a rota /users/:id retorna o usuário com o ID especificado, ou um erro 404 se o usuário não for encontrado.

5. Documentando a API

A documentação é uma parte essencial de qualquer API. Ela permite que outros desenvolvedores compreendam como usar a API. Existem várias ferramentas disponíveis para documentar APIs, mas uma das mais populares é o Swagger. O Swagger permite que você crie uma documentação interativa para a sua API que pode ser visualizada em um navegador web.

Para adicionar a documentação do Swagger à nossa API, primeiro precisamos instalar o pacote swagger-ui-express:

npm install swagger-ui-express --save

Em seguida, podemos adicionar o seguinte código ao arquivo app.js:

const swaggerUi = require('swagger-ui-express');
const swaggerDocument = require('./swagger.json');

app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument));

Este código adiciona a documentação do Swagger à rota /api-docs. O arquivo swagger.json contém a documentação da API no formato JSON. Este arquivo precisa ser criado manualmente e deve seguir a especificação OpenAPI.

A documentação da API é um tópico complexo que merece um capítulo próprio, mas esperamos que este breve tutorial tenha lhe dado uma ideia de como criar uma API REST básica com NodeJS e ExpressJS e como documentá-la. No próximo capítulo, vamos explorar como adicionar autenticação à nossa API.

Próxima página do Ebook Gratuito:

77Criando uma API REST básica com NodeJS e ExpressJS: Testes automatizados

4 minutos