🚀 Aprendendo Swagger com JavaScript

Guia interativo e didático para dominar APIs com Swagger

👋 Bem-vindo! Esta página vai te ensinar Swagger de forma prática e interativa.

Progresso do Aprendizado 0% Completo

🎯 1. O que é Swagger?

Swagger é um conjunto de ferramentas para documentar, testar e consumir APIs REST.

💡 Por que usar Swagger?

Documentação automática da API
Interface visual para testar endpoints
Geração de código cliente
Padronização da documentação

🎮 Demo Interativo: Swagger vs Documentação Tradicional

❌ Documentação Tradicional

POST /users

Cria um novo usuário...

Informações limitadas e estáticas

✅ Com Swagger

Interativo, testável e detalhado

📖 2. Conceitos Fundamentais

🔧 OpenAPI Specification

É o formato padrão para descrever APIs REST. Antes era chamado de "Swagger Specification".

{
  "openapi": "3.0.0",
  "info": {
    "title": "Minha API",
    "version": "1.0.0"
  },
  "paths": {
    "/users": {
      "get": {
        "summary": "Lista usuários"
      }
    }
  }
}

🎯 Componentes Principais

Paths

Endpoints da API (/users, /products)

Schemas

Estrutura dos dados (User, Product)

Parameters

Query, path, header parameters

🎯 Exercício: Identifique os Componentes

Clique nos elementos do código Swagger abaixo:

{
  "info": {
    "title": "Pet Store API"
  },
  "paths": {
    "/pets": {
      "get": {
        "summary": "List pets"
      }
    }
  }
}

💻 3. Prática com JavaScript

🛠️ Como usar Swagger com JavaScript

Vamos aprender 3 formas principais:

1. Swagger UI

Interface visual para testar APIs

2. Swagger Codegen

Gerar código cliente automaticamente

3. Swagger Parser

Validar e processar specs Swagger

🔥 Editor de Código ao Vivo

Edite o código abaixo e veja o resultado em tempo real:

JavaScript Code:

// Exemplo: Criando uma spec Swagger
const swaggerSpec = {
  openapi: '3.0.0',
  info: {
    title: 'Minha API de Pets',
    version: '1.0.0',
    description: 'API para gerenciar pets'
  },
  paths: {
    '/pets': {
      get: {
        summary: 'Lista todos os pets',
        responses: {
          200: {
            description: 'Lista de pets'
          }
        }
      }
    }
  }
};

// Acessando informações da spec
console.log('Título:', swaggerSpec.info.title);
console.log('Endpoints:', Object.keys(swaggerSpec.paths));

Resultado:

// O resultado aparecerá aqui...

🌐 Simulador de API

Teste diferentes endpoints de uma API simulada:

Clique em um endpoint acima para ver a resposta...

🎯 4. Exercícios Interativos

📝 Exercício 1: Complete a Spec Swagger

Complete o código Swagger abaixo adicionando um endpoint POST:

{
  "openapi": "3.0.0",
  "info": {
    "title": "Books API",
    "version": "1.0.0"
  },
  "paths": {
    "/books": {
      "get": {
        "summary": "Get all books"
      }
      // ADICIONE UM ENDPOINT POST AQUI
    }
  }
}

💡 Dica:

Um endpoint POST deve incluir:

Método "post"
Summary descritivo
Resposta 201 (Created)

🎮 Exercício 2: Quiz Swagger

Qual é a versão atual da OpenAPI Specification mais utilizada?

2.0 3.0 4.0

🏆 Desafio Final

Crie uma especificação Swagger completa para uma API de E-commerce!

Requisitos:

Endpoints para produtos: GET, POST, PUT, DELETE
Endpoint para buscar produtos por categoria
Schema para o objeto Product
Respostas de erro apropriadas