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.

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: 127.0.0.1:4567

Criando uma API Simples com Sinatra e Documentando com Swagger UI