<!DOCTYPE html>

Criando uma API Simples com Sinatra e Documentando com Swagger UI

Neste artigo, exploraremos como criar uma API RESTful com Sinatra, um framework web leve para Ruby, e documentá-la usando Swagger UI, uma ferramenta poderosa para documentação de APIs.

Introdução

APIs (Interfaces de Programação de Aplicativos) são cruciais no mundo moderno de desenvolvimento de software. Elas permitem que diferentes sistemas se comuniquem e compartilhem dados de forma eficiente. O uso de APIs tem crescido exponencialmente, impulsionado por tecnologias como a Internet das Coisas (IoT), aplicações móveis e microsserviços.

Sinatra é uma ótima opção para criar APIs RESTful devido à sua simplicidade e flexibilidade. Ele permite que você se concentre na lógica da sua API sem se preocupar com a complexidade de um framework completo. Swagger UI, por sua vez, oferece uma maneira fácil e intuitiva de documentar sua API, tornando-a mais acessível para desenvolvedores e usuários.

Configurando o Ambiente

Antes de começarmos, precisamos configurar o ambiente de desenvolvimento. Certifique-se de ter as seguintes ferramentas instaladas:

Ruby:
https://www.ruby-lang.org/en/
Sinatra: gem install sinatra
Swagger UI: gem install swagger-ui

Criando uma API Sinatra

Vamos criar uma API simples que gerencia uma lista de tarefas. Crie um novo arquivo chamado
app.rb
e adicione o seguinte código:



  require 'sinatra'

  require 'json'

# Lista de tarefas

  $tasks = []

# Rota para criar uma nova tarefa

  post '/tasks' do

    content_type :json

task = JSON.parse(request.body.read)
$tasks &lt;&lt; task

{ message: 'Tarefa criada com sucesso!', task: task }.to_json


end

# Rota para obter todas as tarefas

  get '/tasks' do

    content_type :json

$tasks.to_json


end

# Rota para obter uma tarefa específica

  get '/tasks/:id' do

    content_type :json

id = params[:id].to_i
task = $tasks[id]

if task
  task.to_json
else
  { message: 'Tarefa não encontrada' }.to_json
end


end

# Rota para atualizar uma tarefa

  put '/tasks/:id' do

    content_type :json

id = params[:id].to_i
task = JSON.parse(request.body.read)

if $tasks[id]
  $tasks[id] = task
  { message: 'Tarefa atualizada com sucesso!', task: task }.to_json
else
  { message: 'Tarefa não encontrada' }.to_json
end


end

# Rota para excluir uma tarefa

  delete '/tasks/:id' do

    content_type :json

id = params[:id].to_i

if $tasks[id]
  $tasks.delete_at(id)
  { message: 'Tarefa excluída com sucesso!' }.to_json
else
  { message: 'Tarefa não encontrada' }.to_json
end


end

Este código define cinco rotas que implementam as operações CRUD (Create, Read, Update, Delete) para tarefas. Cada rota usa o método HTTP apropriado (POST, GET, PUT, DELETE) e retorna uma resposta em formato JSON.

Documentando com Swagger UI

Para documentar nossa API, usaremos Swagger UI. Primeiro, precisamos instalar a gem
swagger-ui
e criar um arquivo YAML que define a estrutura da API.

# app.rb
require 'sinatra'
require 'json'
require 'swagger/blocks'

# ... (código da API)

# Definição do Swagger
Swagger::Blocks.configure do |config|
config.api_version = 'v1'
config.base_path = '/'
end

Swagger::Blocks.define do

# ... (definição de recursos e operações)

end

Adicione a seguinte definição de recursos e operações ao bloco

Swagger::Blocks.define

:

Swagger::Blocks.define do

resource 'Tasks' do

api :POST, '/tasks', 'Create Task' do

param :body, :body, :required, 'Task data', 'application/json'

response 201, 'Task created'

response 400, 'Invalid task data'

end

  api :GET, '/tasks', 'Get all Tasks' do
    response 200, 'List of tasks'
  end

  api :GET, '/tasks/{id}', 'Get Task by ID' do
    param :id, :path, :required, 'Task ID'
    response 200, 'Task found'
    response 404, 'Task not found'
  end

  api :PUT, '/tasks/{id}', 'Update Task' do
    param :id, :path, :required, 'Task ID'
    param :body, :body, :required, 'Task data', 'application/json'
    response 200, 'Task updated'
    response 400, 'Invalid task data'
    response 404, 'Task not found'
  end

  api :DELETE, '/tasks/{id}', 'Delete Task' do
    param :id, :path, :required, 'Task ID'
    response 200, 'Task deleted'
    response 404, 'Task not found'
  end
end

end

Esta definição descreve cada rota da API, incluindo os métodos HTTP, parâmetros, respostas esperadas e exemplos. Depois de definir o Swagger, execute o comando

swagger-ui

no terminal para gerar a documentação HTML.

Após executar o comando, abra o arquivo

index.html

no navegador para visualizar a documentação da API. Você verá uma interface intuitiva que mostra as diferentes rotas, parâmetros, exemplos e respostas.

Executando a API

Para executar a API, use o comando

ruby app.rb

no terminal. A API estará disponível em

http://localhost:4567

.

Conclusão

Criar uma API RESTful com Sinatra e documentá-la com Swagger UI é um processo simples e direto. Sinatra oferece a flexibilidade necessária para construir APIs, enquanto Swagger UI fornece uma interface amigável para documentar e compartilhar sua API. Ao usar essas ferramentas, você pode criar APIs bem estruturadas, fáceis de entender e usar.

Lembre-se de seguir as melhores práticas de desenvolvimento de APIs, como:

Usar verbos HTTP apropriados para cada ação.
Retornar respostas com códigos de status HTTP apropriados.
Usar um formato de dados consistente, como JSON.
Implementar autenticação e autorização para proteger sua API.
Testar sua API extensivamente para garantir sua qualidade.

Com as ferramentas e técnicas apresentadas neste artigo, você estará pronto para criar APIs robustas e bem documentadas, facilitando a comunicação entre diferentes sistemas.

$(document).ready(function() { 
// Inicializa o Swagger UI 
SwaggerUIBundle({ 
url: '<a href="http://localhost:4567/swagger.yaml">http://localhost:4567/swagger.yaml</a>&#39;, // URL para o arquivo YAML do Swagger 
dom_id: '#swagger-ui', // ID do elemento HTML para a documentação 
presets: [ 
SwaggerUIBundle.presets.apis, 
SwaggerUIBundle.presets.SwaggerUIStandalonePreset 
], 
layout: 'StandaloneLayout' 
}); 
});