Hoje vou compartilhar um pequeno projeto que desenvolvi: uma API simples de gerenciamento de tarefas utilizando Sinatra com documentação interativa através do Swagger UI. O objetivo deste tutorial é mostrar como construir uma API básica e documentá-la de forma acessível para qualquer desenvolvedor que queira testar e interagir com as rotas disponíveis.
Link do repositório: github
Introdução ao Projeto
A API permite criar, listar e deletar tarefas. O foco principal é integrar a documentação com o Swagger UI para que seja fácil visualizar e testar os endpoints.
Tecnologias Utilizadas
Sinatra: Um micro framework Ruby para construir APIs de forma simples e rápida.
Swagger UI: Um conjunto de ferramentas que ajuda a gerar uma interface gráfica para testar e documentar APIs.
JSON: Formato de dados para a comunicação entre o cliente e a API.
Estrutura Básica da API
Aqui está um exemplo do código da API com as funcionalidades de listar, adicionar e deletar tarefas.
require 'sinatra'
require 'json'
tasks = []
get '/tasks' do
content_type :json
tasks.to_json
end
post '/tasks' do
content_type :json
task = JSON.parse(request.body.read)
tasks << task
task.to_json
end
delete '/tasks' do
content_type :json
title = params['title']
task_to_delete = tasks.find { |task| task['title'] == title }
if task_to_delete
tasks.delete(task_to_delete)
{ status: 'Task deleted' }.to_json
else
status 404
{ error: 'Task not found' }.to_json
end
end
get '/' do
send_file 'index.html'
end
get '/swagger.yaml' do
send_file 'swagger.yaml'
end
Como Adicionar Documentação com Swagger UI
Para facilitar o uso e visualização dos endpoints, integramos o Swagger UI ao projeto. O Swagger gera uma interface gráfica que permite que você faça testes diretamente pelo navegador.
Estrutura do Arquivo Swagger (swagger.yaml)
openapi: 3.0.0
info:
title: TO-DO LIST API
description: A simple API to manage tasks.
version: 1.0.0
paths:
/tasks:
get:
summary: Get all tasks
responses:
'200':
description: A list of tasks
content:
application/json:
schema:
type: array
items:
type: object
properties:
title:
type: string
post:
summary: Add a new task
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
title:
type: string
responses:
'200':
description: Task added successfully
content:
application/json:
schema:
type: object
properties:
title:
type: string
delete:
summary: Delete a task by title
parameters:
- in: query
name: title
required: true
schema:
type: string
responses:
'200':
description: Task deleted successfully
content:
application/json:
schema:
type: object
properties:
status:
type: string
'404':
description: Task not found
content:
application/json:
schema:
type: object
properties:
error:
type: string
Esse arquivo YAML é o que define as rotas da API, os parâmetros e as respostas esperadas. No Swagger UI, ele gera uma interface amigável para que você possa interagir com a API.
HTML para Rodar o Swagger UI
Crie um arquivo index.html para visualizar a interface do Swagger:
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>Swagger UI</title>
<link rel="stylesheet" type="text/css" href="https://unpkg.com/swagger-ui-dist/swagger-ui.css" >
<script src="https://unpkg.com/swagger-ui-dist/swagger-ui-bundle.js"></script>
<script src="https://unpkg.com/swagger-ui-dist/swagger-ui-standalone-preset.js"></script>
</head>
<body>
<div id="swagger-ui"></div>
<script>
SwaggerUIBundle({
url: "swagger.yaml",
dom_id: '#swagger-ui',
presets: [
SwaggerUIBundle.presets.apis,
SwaggerUIStandalonePreset
],
layout: "StandaloneLayout"
});
</script>
</body>
</html>
Com isso, você pode acessar o Swagger UI ao rodar a aplicação.
Rodando o Projeto
Aqui estão os passos para rodar a API localmente:
Clone o repositório:
git clone <https://github.com/bussularf/simple-ruby-api-to-do-list.git>
cd simple_api
bundle
ruby app.rb
No console: use curl para interagir com a API.
exemplo: curl -X GET http://127.0.0.1:4567/tasks
No browser: app url
