DS & II

Capítulo 17 - Documentação com Swagger

Leitura de 3 min

🚀 Capítulo 17: Documentação com Swagger/OpenAPI (Tema: Detona Ralph)

NOTE

Este capítulo utiliza a temática de Detona Ralph para explicar a Documentação. Para o Ralph poder visitar outros jogos sem quebrar nada, ele precisa ler o manual de instruções de cada jogo!

1. 🎯 Objetivo da Aula

Compreender a importância de documentar APIs e como o Swagger (OpenAPI) ajuda a criar uma documentação interativa e fácil de usar.

2. 🏢 O Cenário Prático (Seu Desafio)

O Detona Ralph quer sair do seu jogo e visitar o jogo Corrida Doce. Mas ele não sabe como as coisas funcionam lá! Ele precisa saber quais são as regras, quais personagens existem e o que acontece se ele coletar uma moeda. No mundo do desenvolvimento, quando um programador de Frontend vai usar a sua API, ele passa pela mesma situação. Ele precisa de um manual! Seu desafio é entender como criar esse manual usando o Swagger.

3. 🧠 Fundamentos: A Teoria Traduzida

Uma API sem documentação é como um labirinto no escuro. Ninguém sabe quais caminhos (endpoints) existem ou o que enviar neles.

📜 1. O que é a OpenAPI?

É um padrão (uma especificação) que descreve como deve ser o arquivo de documentação de uma API REST. É um arquivo JSON ou YAML que lista todas as rotas, parâmetros e respostas.

🎨 2. O que é o Swagger?

É o conjunto de ferramentas que lê esse arquivo da OpenAPI e gera uma página web interativa (Swagger UI).

  • O Superpoder: Na própria página do Swagger, você tem um botão “Try it out” (Testar) onde você pode preencher os dados e fazer a requisição de verdade para o servidor, sem precisar digitar nenhuma linha de código!

4. 📖 Exemplo Guiado: O que tem na documentação?

Uma boa documentação Swagger mostra para cada rota:

  1. O Verbo e o Endpoint: POST /pontuacao
  2. A Descrição: “Salva a pontuação do jogador”.
  3. Os Parâmetros: O que precisa enviar (ex: nome e pontos).
  4. As Respostas Possíveis: O que o servidor retorna (ex: 201 Created ou 400 Bad Request).

5. 🛠️ Prática Obrigatória 1: O Manual da Corrida Doce

Imagine que você está documentando a API do jogo Corrida Doce. Descreva como ficaria a documentação para a rota de Listar os Carros:

  1. Qual seria o Verbo HTTP e o Endpoint?
  2. O que o servidor deveria retornar em caso de sucesso (Código de status e tipo de dado)?

6. 🛠️ Prática Obrigatória 2: Vantagem do Swagger

Por que usar o Swagger é muito melhor do que escrever a documentação da API em um arquivo do Word ou PDF? (Dica: Pense no botão de testar).

7. 📤 Instruções de Entrega (GitHub Desktop + Microsoft Teams)

  1. Faça o Commit: No GitHub Desktop, digite a mensagem (ex: Finaliza Capítulo 17 Backend) e clique em Commit to main.
  2. Envie para a Nuvem (Push): Clique em Push origin.

8. 📂 Estrutura de Pastas

mod_07_backend_e_apis/
├── capitulos/
│   ├── capitulo_17_swagger.md
│   └── codigos/
│       └── cap17/
│           └── doc_corrida_doce.txt

9. 💡 Checkpoint de Lógica

Se a documentação do Swagger mostra todas as rotas e até permite testar, qualquer pessoa na internet pode ver e usar as rotas da minha empresa? Como protegemos isso?

10. 🔥 Desafio de Fixação

Pesquise como instalar o pacote swagger-ui-express em um projeto Node.js para gerar a página interativa.

11. 🔑 Gabarito de Código/Fórmulas

Gabarito da Prática 1:

  1. Verbo e Endpoint: GET /carros.
  2. Sucesso: Status 200 OK e uma lista (Array) de objetos JSON contendo os dados dos carros.

← Capitulo Anterior | Proximo Capitulo →

Visão de gráfico

Backlinks