Aula 14 — Documentação com Swagger

openapi: 3.0.0        # versão da especificação usada
info:                  # metadados da API
  title: UniEventos API
  version: 1.0.0
  description: API de eventos acadêmicos do UniEventos
servers:               # onde a API está hospedada (pode ter vários)
  - url: http://localhost:3000
    description: Ambiente local
tags:                  # agrupamento visual dos endpoints no Swagger UI
  - name: Eventos
  - name: Inscrições
  - name: Autenticação
paths:                 # cada endpoint documentado
  /api/eventos:
    get: { ... }
    post: { ... }
components:            # peças reutilizáveis entre paths
  schemas: { ... }        # formatos de objeto (Evento, EventoInput, Erro...)
  securitySchemes: { ... } # como a API autentica (ex.: bearerAuth)

# openapi.yaml (resumo — não é o que vamos usar hoje, é só para você conhecer a alternativa)
openapi: 3.0.0
info:
  title: UniEventos API
  version: 1.0.0
paths:
  /api/eventos:
    get:
      tags: [Eventos]
      summary: Lista eventos
      responses:
        '200':
          description: Lista de eventos

// server.js — servindo o YAML escrito à mão, em vez de gerado por anotação
import { readFileSync } from 'node:fs'
import yaml from 'yaml' // npm install yaml
import swaggerUi from 'swagger-ui-express'

const documentoOpenApi = yaml.parse(readFileSync('./openapi.yaml', 'utf-8'))
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(documentoOpenApi))

<!-- README.md -->
# UniEventos API

![Node.js](https://img.shields.io/badge/node-22.x-green)
![Express](https://img.shields.io/badge/express-5.2.1-blue)
![Licença](https://img.shields.io/badge/licença-MIT-lightgrey)

API REST da plataforma **UniEventos** — divulgação e inscrição em eventos acadêmicos.
Projeto desenvolvido na disciplina em que esta trilha nasceu.

## Requisitos

- Node.js 22 LTS
- MySQL 8 (local ou gerenciado)
- Conta de serviço do Firebase (arquivo de credenciais)

## Instalação

```bash
git clone https://github.com/seu-usuario/unieventos-api.git
cd unieventos-api
npm install
cp .env.example .env   # preencha com suas credenciais
npm run migrar
npm run dev
```

## Variáveis de ambiente

| Variável | Descrição |
|---|---|
| `PORT` | Porta HTTP da API (padrão 3000) |
| `DB_HOST` / `DB_PORT` / `DB_USER` / `DB_PASSWORD` / `DB_NAME` | Credenciais do MySQL |
| `FIREBASE_PROJECT_ID` | Id do projeto Firebase usado na verificação de token |
| `CORS_ORIGEM_PERMITIDA` | Origem do front-end autorizada pelo CORS |

## Scripts disponíveis

| Comando | Efeito |
|---|---|
| `npm run dev` | Sobe a API com recarregamento automático |
| `npm start` | Sobe a API em modo produção |
| `npm test` | Executa a suíte de testes (vitest) |
| `npm run migrar` | Aplica migrations pendentes no banco |

## Endpoints

Documentação interativa completa em `/api-docs` (Swagger UI) com o projeto rodando.
Resumo:

| Método | Rota | Descrição |
|---|---|---|
| GET | `/api/eventos` | Lista eventos, com filtros |
| GET | `/api/eventos/:id` | Detalha um evento |
| POST | `/api/eventos` | Cria evento (autenticado) |
| PUT | `/api/eventos/:id` | Atualiza evento (autenticado) |
| DELETE | `/api/eventos/:id` | Remove evento (autenticado) |
| GET | `/api/inscricoes` | Lista inscrições do usuário logado |
| POST | `/api/inscricoes` | Inscreve o usuário em um evento |
| DELETE | `/api/inscricoes/:id` | Cancela inscrição |

## Licença

MIT — veja o arquivo LICENSE.

<!-- CONTRIBUTING.md -->
# Como contribuir

1. Crie uma branch a partir de `main`: `git checkout -b feature/nome-da-mudanca`.
2. Rode `npm test` antes de abrir o Pull Request — a suíte precisa passar.
3. Siga o padrão de nomes em português para identificadores de domínio (`eventos`, `criarEvento`).
4. Toda rota nova precisa ter anotação `@openapi` correspondente (Aula 14).
5. Abra o Pull Request descrevendo o que mudou e por quê.

// src/composables/useEventos.js
/**
 * Composable que encapsula a busca e o estado de carregamento da lista de eventos.
 *
 * @param {Object} [opcoes] - opções de filtro inicial
 * @param {string} [opcoes.categoria] - categoria para filtrar a busca inicial
 * @returns {{
 *   eventos: import('vue').Ref<Array>,
 *   carregando: import('vue').Ref<boolean>,
 *   erro: import('vue').Ref<string|null>,
 *   buscarEventos: (filtros?: Object) => Promise<void>
 * }}
 */
export function useEventos(opcoes = {}) {
  // implementação já construída na Aula 06/11 — reaproveitada aqui
}

# ADR 0001: <título curto da decisão>

**Status:** aceito | proposto | substituído por ADR-000X


## Contexto
<qual problema motivou esta decisão>

## Decisão
<o que foi decidido>

## Consequências
<o que fica mais fácil, o que fica mais difícil, o que foi trocado por quê>

<!-- docs/adr/0001-escolha-do-repository-pattern.md -->
# ADR 0001: Usar o padrão Repository para acesso a dados

**Status:** aceito


## Contexto
O service de eventos precisava consultar o MySQL diretamente, o que impedia
testar as regras de negócio (ex.: "vagas não pode ser negativo") sem subir
um banco de dados real, e acoplava o service à sintaxe SQL do mysql2.

## Decisão
Extrair toda a lógica de acesso a dados para `repositories/`, com uma
interface comum (`listar`, `buscarPorId`, `criar`, `atualizar`, `remover`),
injetada no service por parâmetro (Dependency Injection). O ambiente de
teste usa uma implementação em memória; produção usa a implementação MySQL.

## Consequências
Testes de service ficaram instantâneos e sem dependência externa. Trocar o
banco de dados (como fizemos ao avaliar Supabase na Aula 12) passou a exigir
apenas uma nova implementação de repositório, sem tocar em services ou
controllers. Custo: uma camada de indireção a mais para quem está lendo o
código pela primeira vez.

/**
 * @openapi
 * /api/eventos:
 *   get:
 *     summary: Lista eventos                    ← "decoração": metadado
 *     tags: [Eventos]                            ← "decoração": metadado
 */
router.get('/', eventosController.listar)         // ← comportamento real, intocado

npm install swagger-jsdoc swagger-ui-express

// src/docs/swaggerSpec.js
import swaggerJsdoc from 'swagger-jsdoc'

// ATENÇÃO: a chave é "definition", NÃO "swaggerDefinition" — swagger-jsdoc 6.x
// renomeou essa chave em relação a versões anteriores. Usar o nome errado faz
// a spec sair vazia, sem erro nenhum no console.
const opcoes = {
  definition: {
    openapi: '3.0.0',
    info: {
      title: 'UniEventos API',
      version: '1.0.0',
      description:
        'API REST da plataforma UniEventos — divulgação e inscrição em eventos acadêmicos. ' +
        'Desenvolvida na disciplina em que esta trilha nasceu.',
      contact: {
        name: 'Equipe UniEventos',
        email: 'contato@unieventos.exemplo',
      },
      license: {
        name: 'MIT',
      },
    },
    servers: [
      { url: 'http://localhost:3000', description: 'Ambiente local' },
      { url: 'https://unieventos-api.onrender.com', description: 'Produção' },
    ],
    tags: [
      { name: 'Eventos', description: 'Cadastro e consulta de eventos acadêmicos' },
      { name: 'Inscrições', description: 'Inscrição de usuários autenticados em eventos' },
      { name: 'Autenticação', description: 'Fluxo de login com Firebase Auth' },
    ],
    components: {
      securitySchemes: {
        bearerAuth: {
          type: 'http',
          scheme: 'bearer',
          bearerFormat: 'JWT',
          description: 'Token de ID do Firebase Auth, obtido após o login no front-end.',
        },
      },
    },
  },
  // Arquivos onde o swagger-jsdoc procura comentários @openapi.
  apis: ['./src/routes/*.js', './src/docs/schemas/*.js'],
}

export const swaggerSpec = swaggerJsdoc(opcoes)

// src/app.js — trecho adicionado à montagem da aplicação (depois das rotas de negócio)
import swaggerUi from 'swagger-ui-express'
import { swaggerSpec } from './docs/swaggerSpec.js'

// Opções de customização visual do Swagger UI.
const opcoesDoSwaggerUi = {
  customSiteTitle: 'UniEventos API — Documentação',
  customCss: '.swagger-ui .topbar { display: none }', // esconde a barra verde padrão
}

app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerSpec, opcoesDoSwaggerUi))

// Expõe o JSON cru da spec — útil para importar em Insomnia/Postman
// ou para ferramentas de geração de cliente consumirem diretamente.
app.get('/api-docs.json', (req, res) => {
  res.status(200).json(swaggerSpec)
})

npm run dev
# abra no navegador:
# http://localhost:3000/api-docs       → interface interativa
# http://localhost:3000/api-docs.json  → JSON cru da especificação

// src/docs/schemas/evento.schema.js
/**
 * @openapi
 * components:
 *   schemas:
 *     Evento:
 *       type: object
 *       properties:
 *         id:
 *           type: integer
 *           example: 3
 *         titulo:
 *           type: string
 *           example: Hackathon de Tecnologia
 *         descricao:
 *           type: string
 *           example: Maratona de programação de 24 horas aberta a todos os cursos.
 *         categoria:
 *           type: string
 *           enum: [palestra, minicurso, workshop]
 *           example: workshop
 *         dataHora:
 *           type: string
 *           format: date-time
 *           example: 2030-10-05T08:00:00
 *         local:
 *           type: string
 *           example: Bloco A, Auditório
 *         vagas:
 *           type: integer
 *           example: 60
 *         imagemUrl:
 *           type: string
 *           format: uri
 *           example: https://storage.unieventos.dev/eventos/hackathon.jpg
 *
 *     EventoInput:
 *       type: object
 *       required: [titulo, categoria, dataHora, local, vagas]
 *       properties:
 *         titulo:
 *           type: string
 *           minLength: 3
 *           maxLength: 150
 *         descricao:
 *           type: string
 *         categoria:
 *           type: string
 *           enum: [palestra, minicurso, workshop]
 *         dataHora:
 *           type: string
 *           format: date-time
 *         local:
 *           type: string
 *         vagas:
 *           type: integer
 *           minimum: 0
 *         imagemUrl:
 *           type: string
 *           format: uri
 *
 *     Erro:
 *       type: object
 *       description: Envelope único de erro da API, fixado na Aula 08.
 *       properties:
 *         erro:
 *           type: object
 *           properties:
 *             mensagem:
 *               type: string
 *               example: Evento não encontrado
 *             codigo:
 *               type: string
 *               example: NAO_ENCONTRADO
 *             detalhes:
 *               type: array
 *               description: Presente apenas em erros de validação (422).
 *               items:
 *                 type: object
 *                 properties:
 *                   campo:
 *                     type: string
 *                   mensagem:
 *                     type: string
 *
 *     Paginacao:
 *       type: object
 *       properties:
 *         pagina:
 *           type: integer
 *           example: 1
 *         porPagina:
 *           type: integer
 *           example: 20
 *         total:
 *           type: integer
 *           example: 47
 *         totalPaginas:
 *           type: integer
 *           example: 3
 *
 *     ListaDeEventos:
 *       type: object
 *       description: Envelope de listagem da API — { dados, paginacao }.
 *       properties:
 *         dados:
 *           type: array
 *           items:
 *             $ref: '#/components/schemas/Evento'
 *         paginacao:
 *           $ref: '#/components/schemas/Paginacao'
 */
export {} // arquivo só existe para hospedar o comentário — sem código de fato

// src/docs/schemas/inscricao.schema.js
/**
 * @openapi
 * components:
 *   schemas:
 *     Inscricao:
 *       type: object
 *       properties:
 *         id:
 *           type: integer
 *           example: 12
 *         eventoId:
 *           type: integer
 *           example: 3
 *         usuarioUid:
 *           type: string
 *           example: fY3k9sLp2QaB1cD4eF5gH6iJ7kL8
 *         criadoEm:
 *           type: string
 *           format: date-time
 *
 *     InscricaoInput:
 *       type: object
 *       required: [eventoId]
 *       properties:
 *         eventoId:
 *           type: integer
 *           example: 3
 */
export {}

// src/routes/eventos.routes.js — versão anotada
import { Router } from 'express'
import { validar } from '../middlewares/validar.js'
import { eventoSchema, eventoAtualizacaoSchema } from '../validators/eventoSchema.js'
import { autenticar } from '../middlewares/autenticar.js'
import { autorizar } from '../middlewares/autorizar.js'

export function criarRotasDeEventos({ eventosController }) {
  const router = Router()

  /**
   * @openapi
   * /api/eventos:
   *   get:
   *     summary: Lista eventos, com filtros opcionais
   *     tags: [Eventos]
   *     parameters:
   *       - in: query
   *         name: categoria
   *         schema:
   *           type: string
   *           enum: [palestra, minicurso, workshop]
   *         description: Filtra por categoria do evento
   *       - in: query
   *         name: busca
   *         schema:
   *           type: string
   *         description: Filtra por trecho do título
   *       - in: query
   *         name: pagina
   *         schema:
   *           type: integer
   *           default: 1
   *       - in: query
   *         name: porPagina
   *         schema:
   *           type: integer
   *           default: 20
   *     responses:
   *       200:
   *         description: Lista paginada de eventos, no envelope { dados, paginacao }
   *         content:
   *           application/json:
   *             schema:
   *               $ref: '#/components/schemas/ListaDeEventos'
   */
  router.get('/', eventosController.listar)

  /**
   * @openapi
   * /api/eventos/{id}:
   *   get:
   *     summary: Busca um evento pelo id
   *     tags: [Eventos]
   *     parameters:
   *       - in: path
   *         name: id
   *         required: true
   *         schema:
   *           type: integer
   *         description: Id numérico do evento
   *     responses:
   *       200:
   *         description: Evento encontrado
   *         content:
   *           application/json:
   *             schema:
   *               $ref: '#/components/schemas/Evento'
   *       404:
   *         description: Evento não encontrado
   *         content:
   *           application/json:
   *             schema:
   *               $ref: '#/components/schemas/Erro'
   */
  router.get('/:id', eventosController.buscarPorId)

  /**
   * @openapi
   * /api/eventos:
   *   post:
   *     summary: Cria um novo evento
   *     tags: [Eventos]
   *     security:
   *       - bearerAuth: []
   *     requestBody:
   *       required: true
   *       content:
   *         application/json:
   *           schema:
   *             $ref: '#/components/schemas/EventoInput'
   *     responses:
   *       201:
   *         description: Evento criado
   *         content:
   *           application/json:
   *             schema:
   *               $ref: '#/components/schemas/Evento'
   *       400:
   *         description: Dados inválidos
   *         content:
   *           application/json:
   *             schema:
   *               $ref: '#/components/schemas/Erro'
   *       401:
   *         description: Token ausente ou inválido
   *         content:
   *           application/json:
   *             schema:
   *               $ref: '#/components/schemas/Erro'
   */
  router.post('/', autenticar, validar(eventoSchema), eventosController.criar)

  /**
   * @openapi
   * /api/eventos/{id}:
   *   put:
   *     summary: Atualiza um evento existente
   *     tags: [Eventos]
   *     security:
   *       - bearerAuth: []
   *     parameters:
   *       - in: path
   *         name: id
   *         required: true
   *         schema:
   *           type: integer
   *     requestBody:
   *       required: true
   *       content:
   *         application/json:
   *           schema:
   *             $ref: '#/components/schemas/EventoInput'
   *     responses:
   *       200:
   *         description: Evento atualizado
   *         content:
   *           application/json:
   *             schema:
   *               $ref: '#/components/schemas/Evento'
   *       404:
   *         description: Evento não encontrado
   *         content:
   *           application/json:
   *             schema:
   *               $ref: '#/components/schemas/Erro'
   */
  router.put('/:id', autenticar, validar(eventoAtualizacaoSchema), eventosController.atualizar)

  /**
   * @openapi
   * /api/eventos/{id}:
   *   delete:
   *     summary: Remove um evento
   *     tags: [Eventos]
   *     security:
   *       - bearerAuth: []
   *     parameters:
   *       - in: path
   *         name: id
   *         required: true
   *         schema:
   *           type: integer
   *     responses:
   *       204:
   *         description: Evento removido com sucesso, sem corpo de resposta
   *       404:
   *         description: Evento não encontrado
   *         content:
   *           application/json:
   *             schema:
   *               $ref: '#/components/schemas/Erro'
   */
  router.delete('/:id', autenticar, autorizar(['admin']), eventosController.remover)

  return router
}

// src/routes/inscricoes.routes.js — versão anotada
import { Router } from 'express'
import { validar } from '../middlewares/validar.js'
import { inscricaoSchema } from '../validators/inscricaoSchema.js'
import { autenticar } from '../middlewares/autenticar.js'
import { autorizar } from '../middlewares/autorizar.js'

export function criarRotasDeInscricoes({ inscricoesController }) {
  const router = Router()

  /**
   * @openapi
   * /api/inscricoes:
   *   get:
   *     summary: Lista as inscrições do usuário autenticado
   *     tags: [Inscrições]
   *     security:
   *       - bearerAuth: []
   *     responses:
   *       200:
   *         description: Lista de inscrições do usuário logado
   *         content:
   *           application/json:
   *             schema:
   *               type: array
   *               items:
   *                 $ref: '#/components/schemas/Inscricao'
   *       401:
   *         description: Token ausente ou inválido
   */
  router.get('/', autenticar, inscricoesController.listarMinhas)

  /**
   * @openapi
   * /api/inscricoes:
   *   post:
   *     summary: Inscreve o usuário autenticado em um evento
   *     tags: [Inscrições]
   *     security:
   *       - bearerAuth: []
   *     requestBody:
   *       required: true
   *       content:
   *         application/json:
   *           schema:
   *             $ref: '#/components/schemas/InscricaoInput'
   *     responses:
   *       201:
   *         description: Inscrição criada
   *         content:
   *           application/json:
   *             schema:
   *               $ref: '#/components/schemas/Inscricao'
   *       409:
   *         description: Usuário já está inscrito neste evento
   *         content:
   *           application/json:
   *             schema:
   *               $ref: '#/components/schemas/Erro'
   */
  router.post('/', autenticar, validar(inscricaoSchema), inscricoesController.criar)

  /**
   * @openapi
   * /api/inscricoes/{id}:
   *   delete:
   *     summary: Cancela uma inscrição do próprio usuário
   *     tags: [Inscrições]
   *     security:
   *       - bearerAuth: []
   *     parameters:
   *       - in: path
   *         name: id
   *         required: true
   *         schema:
   *           type: integer
   *     responses:
   *       204:
   *         description: Inscrição cancelada
   *       403:
   *         description: A inscrição pertence a outro usuário
   *         content:
   *           application/json:
   *             schema:
   *               $ref: '#/components/schemas/Erro'
   */
  router.delete('/:id', autenticar, inscricoesController.cancelar)

  return router
}

// src/routes/autenticacao.routes.js
import { Router } from 'express'
import { autenticar } from '../middlewares/autenticar.js'

export function criarRotasDeAutenticacao() {
  const router = Router()

  /**
   * @openapi
   * /api/auth/verificar:
   *   get:
   *     summary: Confirma se o token enviado é válido e devolve os dados do usuário
   *     description: >
   *       Não existe endpoint de login nesta API — o login acontece no front-end,
   *       diretamente contra o Firebase Auth (signInWithEmailAndPassword). Este
   *       endpoint serve apenas para confirmar que um token de ID do Firebase é válido.
   *     tags: [Autenticação]
   *     security:
   *       - bearerAuth: []
   *     responses:
   *       200:
   *         description: Token válido
   *         content:
   *           application/json:
   *             schema:
   *               type: object
   *               properties:
   *                 uid:
   *                   type: string
   *                 email:
   *                   type: string
   *       401:
   *         description: Token ausente, expirado ou inválido
   *         content:
   *           application/json:
   *             schema:
   *               $ref: '#/components/schemas/Erro'
   */
  // o `autenticar` NÃO é decorativo: é ele que valida o token e preenche
  // `req.usuario`. Sem ele, a anotação promete 401 e o handler estoura 500.
  router.get('/verificar', autenticar, (req, res) => {
    res.status(200).json({ uid: req.usuario.uid, email: req.usuario.email })
  })

  return router
}

securitySchemes:
  bearerAuth:
    type: http
    scheme: bearer
    bearerFormat: JWT

const opcoes = {
  ______________: { openapi: '3.0.0', info: { title: 'UniEventos API', version: '1.0.0' } },
  apis: ['./src/routes/*.js'],
}

responses:
  200:
    content:
      application/json:
        schema:
          $ref: '#/components/schema/Evento'