acai-ui 1.65.5

package/src/components/swagger/openapi-normalizar.ts

@@ -0,0 +1,514 @@
+import {
+  METODOS_HTTP,
+  type ApiNormalizada,
+  type CorpoNormalizado,
+  type DocumentoOpenApi,
+  type GrupoNormalizado,
+  type ItemPathOpenApi,
+  type MetodoHttp,
+  type OperacaoNormalizada,
+  type OperacaoOpenApi,
+  type ParametroNormalizado,
+  type ParametroOpenApi,
+  type RespostaNormalizada,
+  type SchemaOpenApi,
+} from './openapi-tipos'
+
+/** Grupo usado quando a operação não declara tag. Mesmo rótulo do Swagger UI. */
+const GRUPO_PADRAO = 'default'
+
+/** Profundidade máxima ao gerar exemplo — corta schema recursivo (Pessoa.chefe: Pessoa). */
+const PROFUNDIDADE_MAX = 6
+
+// =============================================================
+// Resolução de $ref
+// =============================================================
+
+/**
+ * Resolve um `$ref` interno (`#/components/schemas/Pessoa`) percorrendo o
+ * documento. Só trata referência LOCAL: `$ref` para arquivo externo ou URL
+ * exigiria buscar outro documento, e nenhuma spec de Spring Boot gera isso.
+ */
+function resolverRef<T>(doc: DocumentoOpenApi, ref: string): T | null {
+  if (!ref.startsWith('#/')) return null
+
+  const partes = ref
+    .slice(2)
+    .split('/')
+    // JSON Pointer escapa `/` como ~1 e `~` como ~0.
+    .map((p) => p.replace(/~1/g, '/').replace(/~0/g, '~'))
+
+  let atual: unknown = doc
+  for (const parte of partes) {
+    if (atual === null || typeof atual !== 'object') return null
+    atual = (atual as Record<string, unknown>)[parte]
+  }
+  return (atual as T) ?? null
+}
+
+/**
+ * Segue a cadeia de `$ref` até o objeto concreto.
+ *
+ * O `vistos` existe porque spec real tem ciclo — um `$ref` que aponta pra si
+ * mesmo direta ou indiretamente trava o processo sem ele. Preferimos devolver
+ * o último nó ao invés de estourar a pilha.
+ */
+function derreferenciar<T extends { $ref?: string }>(
+  doc: DocumentoOpenApi,
+  no: T | undefined | null,
+  vistos: Set<string> = new Set(),
+): T | null {
+  if (!no) return null
+  if (!no.$ref) return no
+
+  if (vistos.has(no.$ref)) return null
+  vistos.add(no.$ref)
+
+  const alvo = resolverRef<T>(doc, no.$ref)
+  if (!alvo) return null
+  return derreferenciar(doc, alvo, vistos)
+}
+
+/**
+ * Achata `allOf` num schema só. É como o OpenAPI expressa herança, e é o caso
+ * que mais aparece em Spring Boot (DTO que estende outro): sem achatar, a tela
+ * mostraria um objeto sem nenhuma propriedade.
+ *
+ * `oneOf`/`anyOf` NÃO são combinados — não existe um objeto único que os
+ * represente. Adotamos o primeiro ramo, que é o que o Swagger UI mostra por
+ * padrão no exemplo.
+ */
+export function achatarSchema(
+  doc: DocumentoOpenApi,
+  schema: SchemaOpenApi | undefined | null,
+  vistos: Set<string> = new Set(),
+): SchemaOpenApi | null {
+  const base = derreferenciar(doc, schema, new Set(vistos))
+  if (!base) return null
+
+  if (base.allOf?.length) {
+    const combinado: SchemaOpenApi = { type: 'object', properties: {}, required: [] }
+
+    // Sob `exactOptionalPropertyTypes` (ligado neste tsconfig), atribuir
+    // `undefined` a prop opcional é erro — daí o guarda antes de cada escrita
+    // em vez de `??=` direto.
+    const definirDescricao = (valor: string | undefined): void => {
+      if (valor !== undefined && combinado.description === undefined) {
+        combinado.description = valor
+      }
+    }
+
+    for (const parte of base.allOf) {
+      const achatado = achatarSchema(doc, parte, vistos)
+      if (!achatado) continue
+      Object.assign(combinado.properties!, achatado.properties ?? {})
+      combinado.required!.push(...(achatado.required ?? []))
+      // Metadados do primeiro que tiver — descrição costuma vir do ramo pai.
+      definirDescricao(achatado.description)
+      if (achatado.type !== undefined) combinado.type = achatado.type
+    }
+
+    // O próprio nó do allOf pode declarar propriedades junto dos ramos.
+    Object.assign(combinado.properties!, base.properties ?? {})
+    combinado.required!.push(...(base.required ?? []))
+    definirDescricao(base.description)
+
+    combinado.required = Array.from(new Set(combinado.required))
+    return combinado
+  }
+
+  const ramo = base.oneOf?.[0] ?? base.anyOf?.[0]
+  if (ramo) return achatarSchema(doc, ramo, vistos)
+
+  return base
+}
+
+// =============================================================
+// Legibilidade e exemplo
+// =============================================================
+
+/** Nome do tipo como o Swagger UI mostra: `string($date)`, `array<Pessoa>`. */
+export function descreverTipo(
+  doc: DocumentoOpenApi,
+  schema: SchemaOpenApi | undefined | null,
+  profundidade = 0,
+): string {
+  if (!schema || profundidade > PROFUNDIDADE_MAX) return 'unknown'
+
+  // Antes de derreferenciar: o NOME do ref é a informação mais útil na lista.
+  if (schema.$ref) {
+    const nome = schema.$ref.split('/').pop()
+    if (nome) return nome
+  }
+
+  const resolvido = derreferenciar(doc, schema)
+  if (!resolvido) return 'unknown'
+
+  if (resolvido.enum?.length) return `enum(${resolvido.enum.join(' | ')})`
+
+  if (resolvido.type === 'array') {
+    return `array<${descreverTipo(doc, resolvido.items, profundidade + 1)}>`
+  }
+
+  if (resolvido.allOf?.length || resolvido.oneOf?.length || resolvido.anyOf?.length) {
+    const primeiro = resolvido.allOf?.[0] ?? resolvido.oneOf?.[0] ?? resolvido.anyOf?.[0]
+    return descreverTipo(doc, primeiro, profundidade + 1)
+  }
+
+  if (!resolvido.type) return 'object'
+  return resolvido.format ? `${resolvido.type}(${resolvido.format})` : resolvido.type
+}
+
+/** Valor de partida por formato/tipo, para o corpo vir preenchido e editável. */
+function valorPadrao(schema: SchemaOpenApi): unknown {
+  if (schema.example !== undefined) return schema.example
+  if (schema.default !== undefined) return schema.default
+  if (schema.enum?.length) return schema.enum[0]
+
+  switch (schema.format) {
+    case 'date':
+      return '2026-01-31'
+    case 'date-time':
+      return '2026-01-31T12:00:00Z'
+    case 'uuid':
+      return '00000000-0000-0000-0000-000000000000'
+    case 'email':
+      return 'usuario@exemplo.com'
+    case 'binary':
+      return ''
+    default:
+      break
+  }
+
+  switch (schema.type) {
+    case 'string':
+      return 'string'
+    case 'integer':
+      return 0
+    case 'number':
+      return 0
+    case 'boolean':
+      return true
+    default:
+      return null
+  }
+}
+
+/**
+ * Monta um exemplo de payload a partir do schema — é o que o Swagger UI põe na
+ * caixa de edição do corpo. Campos `readOnly` ficam de fora: são de resposta, e
+ * mandá-los de volta costuma dar 400.
+ */
+export function gerarExemplo(
+  doc: DocumentoOpenApi,
+  schema: SchemaOpenApi | undefined | null,
+  profundidade = 0,
+): unknown {
+  if (!schema || profundidade > PROFUNDIDADE_MAX) return null
+
+  const resolvido = achatarSchema(doc, schema)
+  if (!resolvido) return null
+
+  if (resolvido.example !== undefined) return resolvido.example
+
+  if (resolvido.type === 'array') {
+    const item = gerarExemplo(doc, resolvido.items, profundidade + 1)
+    return item === null ? [] : [item]
+  }
+
+  if (resolvido.properties) {
+    const saida: Record<string, unknown> = {}
+    for (const [nome, prop] of Object.entries(resolvido.properties)) {
+      const propResolvida = derreferenciar(doc, prop)
+      if (propResolvida?.readOnly) continue
+      saida[nome] = gerarExemplo(doc, prop, profundidade + 1)
+    }
+    return saida
+  }
+
+  return valorPadrao(resolvido)
+}
+
+// =============================================================
+// Normalização do documento
+// =============================================================
+
+/**
+ * Versão do schema pronta pra exibição como JSON: resolve `$ref` e `allOf`
+ * recursivamente, para o leitor não cair num `{"$ref": "#/components/..."}`
+ * que não diz nada.
+ *
+ * O corte por profundidade é obrigatório, não estético: schema de Spring Boot
+ * costuma ser cíclico (`Pessoa.chefe: Pessoa`) e a recursão não terminaria.
+ * Ao cortar, devolve o NOME do tipo em vez de sumir com a informação.
+ */
+export function resolverSchemaParaExibicao(
+  doc: DocumentoOpenApi,
+  schema: SchemaOpenApi | null | undefined,
+  profundidade = 0,
+): unknown {
+  const LIMITE = 6
+  const base = achatarSchema(doc, schema ?? null)
+  if (!base) return null
+
+  if (profundidade >= LIMITE) {
+    return base.title ?? nomeDoRef(schema) ?? base.type ?? 'object'
+  }
+
+  const saida: Record<string, unknown> = {}
+  if (base.type) saida.type = base.type
+  if (base.format) saida.format = base.format
+  if (base.description) saida.description = base.description
+  if (base.enum?.length) saida.enum = base.enum
+  if (base.required?.length) saida.required = base.required
+  if (base.nullable) saida.nullable = true
+  if (base.readOnly) saida.readOnly = true
+  if (base.deprecated) saida.deprecated = true
+
+  if (base.items) {
+    saida.items = resolverSchemaParaExibicao(doc, base.items, profundidade + 1)
+  }
+
+  if (base.properties) {
+    saida.properties = Object.fromEntries(
+      Object.entries(base.properties).map(([nome, filho]) => [
+        nome,
+        resolverSchemaParaExibicao(doc, filho, profundidade + 1),
+      ]),
+    )
+  }
+
+  return saida
+}
+
+/** `#/components/schemas/Pessoa` → `Pessoa`. Só pro corte de profundidade. */
+function nomeDoRef(schema: SchemaOpenApi | null | undefined): string | null {
+  const ref = schema?.$ref
+  if (!ref) return null
+  const partes = ref.split('/')
+  return partes[partes.length - 1] ?? null
+}
+
+/**
+ * Valores fechados que o campo aceita, se houver.
+ *
+ * Cobre três formas que aparecem em spec de Spring Boot:
+ *  - `enum` direto no schema do parâmetro;
+ *  - `type: boolean`, que só aceita `true`/`false`;
+ *  - `array` cujo `items` tem enum (`?status=ATIVO&status=INATIVO`).
+ *
+ * Passa por `achatarSchema` porque o enum quase sempre chega atrás de um
+ * `$ref` (`#/components/schemas/StatusServidor`) — ler `schema.enum` cru
+ * devolveria vazio na maioria das specs reais.
+ */
+export function opcoesDoSchema(
+  doc: DocumentoOpenApi,
+  schema: SchemaOpenApi | null | undefined,
+): string[] {
+  const resolvido = achatarSchema(doc, schema ?? null)
+  if (!resolvido) return []
+
+  if (resolvido.enum?.length) {
+    return resolvido.enum.filter((valor) => valor !== null).map((valor) => String(valor))
+  }
+
+  if (resolvido.type === 'boolean') return ['true', 'false']
+
+  if (resolvido.type === 'array') {
+    const item = achatarSchema(doc, resolvido.items)
+    if (item?.enum?.length) {
+      return item.enum.filter((valor) => valor !== null).map((valor) => String(valor))
+    }
+    if (item?.type === 'boolean') return ['true', 'false']
+  }
+
+  return []
+}
+
+function normalizarParametro(
+  doc: DocumentoOpenApi,
+  bruto: ParametroOpenApi,
+): ParametroNormalizado | null {
+  const p = derreferenciar(doc, bruto)
+  if (!p?.name) return null
+
+  return {
+    nome: p.name,
+    onde: p.in ?? 'query',
+    descricao: p.description ?? '',
+    obrigatorio: p.required === true || p.in === 'path',
+    depreciado: p.deprecated === true,
+    schema: p.schema ?? {},
+    tipo: descreverTipo(doc, p.schema),
+    exemplo: p.example ?? (p.schema ? valorPadrao(p.schema) : undefined),
+    opcoes: opcoesDoSchema(doc, p.schema),
+  }
+}
+
+/** Prioriza JSON: é o que praticamente todo endpoint Spring Boot usa. */
+function escolherTipoConteudo(tipos: string[]): string {
+  return tipos.find((t) => t.includes('json')) ?? tipos[0] ?? 'application/json'
+}
+
+function normalizarCorpo(
+  doc: DocumentoOpenApi,
+  operacao: OperacaoOpenApi,
+): CorpoNormalizado | null {
+  const corpo = derreferenciar(doc, operacao.requestBody)
+  if (!corpo?.content) return null
+
+  const tiposConteudo = Object.keys(corpo.content)
+  if (tiposConteudo.length === 0) return null
+
+  const tipoConteudoPadrao = escolherTipoConteudo(tiposConteudo)
+  const schema = corpo.content[tipoConteudoPadrao]?.schema ?? null
+  const exemploDeclarado = corpo.content[tipoConteudoPadrao]?.example
+
+  return {
+    obrigatorio: corpo.required === true,
+    descricao: corpo.description ?? '',
+    tiposConteudo,
+    tipoConteudoPadrao,
+    schema,
+    exemplo: exemploDeclarado ?? gerarExemplo(doc, schema),
+  }
+}
+
+function normalizarRespostas(
+  doc: DocumentoOpenApi,
+  operacao: OperacaoOpenApi,
+): RespostaNormalizada[] {
+  const respostas = operacao.responses ?? {}
+
+  return Object.entries(respostas)
+    .map(([status, bruta]) => {
+      const r = derreferenciar(doc, bruta)
+      const tipos = r?.content ? Object.keys(r.content) : []
+      const tipoConteudo = tipos.length ? escolherTipoConteudo(tipos) : null
+      const schema = tipoConteudo ? (r?.content?.[tipoConteudo]?.schema ?? null) : null
+
+      return {
+        status,
+        descricao: r?.description ?? '',
+        tipoConteudo,
+        schema,
+        exemplo: schema ? gerarExemplo(doc, schema) : null,
+      }
+    })
+    .sort((a, b) => a.status.localeCompare(b.status, undefined, { numeric: true }))
+}
+
+/**
+ * Um documento sem `security` global nem por operação não exige token. Serve
+ * pra tela avisar quando a chamada vai sair sem autenticação.
+ */
+function exigeAutenticacao(doc: DocumentoOpenApi, operacao: OperacaoOpenApi): boolean {
+  if (operacao.security !== undefined) return operacao.security.length > 0
+  const globalSecurity = (doc as { security?: unknown[] }).security
+  return Array.isArray(globalSecurity) && globalSecurity.length > 0
+}
+
+function normalizarOperacao(
+  doc: DocumentoOpenApi,
+  path: string,
+  metodo: MetodoHttp,
+  operacao: OperacaoOpenApi,
+  parametrosDoPath: ParametroOpenApi[],
+): OperacaoNormalizada {
+  // Parâmetros do path-item valem para todas as operações; os da operação
+  // sobrescrevem quando coincidem nome+localizacao (regra da própria spec).
+  const combinados = [...parametrosDoPath, ...(operacao.parameters ?? [])]
+  const porChave = new Map<string, ParametroNormalizado>()
+
+  for (const bruto of combinados) {
+    const p = normalizarParametro(doc, bruto)
+    if (p) porChave.set(`${p.onde}:${p.nome}`, p)
+  }
+
+  return {
+    id: operacao.operationId || `${metodo}:${path}`,
+    metodo,
+    path,
+    resumo: operacao.summary ?? '',
+    descricao: operacao.description ?? '',
+    depreciada: operacao.deprecated === true,
+    tags: operacao.tags?.length ? operacao.tags : [GRUPO_PADRAO],
+    parametros: Array.from(porChave.values()),
+    corpo: normalizarCorpo(doc, operacao),
+    respostas: normalizarRespostas(doc, operacao),
+    exigeAutenticacao: exigeAutenticacao(doc, operacao),
+  }
+}
+
+/**
+ * Converte o documento OpenAPI cru no modelo que a tela renderiza: agrupa por
+ * tag, resolve `$ref`, achata `allOf` e gera exemplos.
+ *
+ * Não lança: spec malformada devolve o que deu pra aproveitar. A tela de um
+ * explorador de API não pode sumir porque um endpoint tem schema quebrado.
+ */
+export function normalizarOpenApi(doc: DocumentoOpenApi | null | undefined): ApiNormalizada {
+  const vazio: ApiNormalizada = {
+    titulo: '',
+    versao: '',
+    descricao: '',
+    servidores: [],
+    grupos: [],
+    totalOperacoes: 0,
+  }
+  if (!doc || typeof doc !== 'object') return vazio
+
+  // OpenAPI 2.0 guardava schemas em `definitions`; espelhar em `components`
+  // faz os `$ref` de spec antiga resolverem sem um caminho separado no código.
+  if (doc.definitions && !doc.components?.schemas) {
+    doc.components = { ...doc.components, schemas: doc.definitions }
+  }
+
+  const porTag = new Map<string, OperacaoNormalizada[]>()
+  let total = 0
+
+  for (const [path, itemBruto] of Object.entries(doc.paths ?? {})) {
+    const item = derreferenciar<ItemPathOpenApi>(doc, itemBruto as ItemPathOpenApi)
+    if (!item) continue
+
+    const parametrosDoPath = item.parameters ?? []
+
+    for (const metodo of METODOS_HTTP) {
+      const operacao = item[metodo]
+      if (!operacao) continue
+
+      const normalizada = normalizarOperacao(doc, path, metodo, operacao, parametrosDoPath)
+      total += 1
+
+      for (const tag of normalizada.tags) {
+        const lista = porTag.get(tag) ?? []
+        lista.push(normalizada)
+        porTag.set(tag, lista)
+      }
+    }
+  }
+
+  const descricaoDaTag = new Map((doc.tags ?? []).map((t) => [t.name ?? '', t.description ?? '']))
+
+  // Ordem das tags declaradas na spec primeiro (é a ordem que o backend quis),
+  // e o resto em ordem alfabética.
+  const declaradas = (doc.tags ?? []).map((t) => t.name ?? '').filter((n) => porTag.has(n))
+  const restantes = Array.from(porTag.keys())
+    .filter((n) => !declaradas.includes(n))
+    .sort((a, b) => a.localeCompare(b))
+
+  const grupos: GrupoNormalizado[] = [...declaradas, ...restantes].map((nome) => ({
+    nome,
+    descricao: descricaoDaTag.get(nome) ?? '',
+    operacoes: porTag.get(nome) ?? [],
+  }))
+
+  return {
+    titulo: doc.info?.title ?? '',
+    versao: doc.info?.version ?? '',
+    descricao: doc.info?.description ?? '',
+    servidores: (doc.servers ?? []).map((s) => s.url ?? '').filter(Boolean),
+    grupos,
+    totalOperacoes: total,
+  }
+}

package/src/components/swagger/openapi-tipos.ts

@@ -0,0 +1,198 @@
+// Tipos MÍNIMOS do OpenAPI 3.x — só o que a tela consome.
+//
+// Deliberadamente não é o schema completo do OpenAPI: modelar a especificação
+// inteira custaria centenas de linhas e nada disso é renderizado. O que não
+// está aqui é ignorado com seguranca, e o `unknown` no fim de cada tipo deixa
+// a spec real passar sem quebrar tipagem.
+
+export type MetodoHttp = 'get' | 'put' | 'post' | 'delete' | 'patch' | 'head' | 'options'
+
+/** Métodos na ordem em que o Swagger UI os apresenta dentro de um path. */
+export const METODOS_HTTP: MetodoHttp[] = [
+  'get',
+  'put',
+  'post',
+  'delete',
+  'patch',
+  'head',
+  'options',
+]
+
+export interface SchemaOpenApi {
+  $ref?: string
+  type?: string
+  format?: string
+  title?: string
+  description?: string
+  example?: unknown
+  default?: unknown
+  enum?: unknown[]
+  required?: string[]
+  nullable?: boolean
+  readOnly?: boolean
+  writeOnly?: boolean
+  deprecated?: boolean
+  properties?: Record<string, SchemaOpenApi>
+  additionalProperties?: SchemaOpenApi | boolean
+  items?: SchemaOpenApi
+  allOf?: SchemaOpenApi[]
+  oneOf?: SchemaOpenApi[]
+  anyOf?: SchemaOpenApi[]
+  /** Restrições que viram dica no formulário. */
+  minimum?: number
+  maximum?: number
+  minLength?: number
+  maxLength?: number
+  pattern?: string
+}
+
+export interface ParametroOpenApi {
+  $ref?: string
+  name?: string
+  in?: 'query' | 'header' | 'path' | 'cookie'
+  description?: string
+  required?: boolean
+  deprecated?: boolean
+  schema?: SchemaOpenApi
+  example?: unknown
+}
+
+export interface MediaTypeOpenApi {
+  schema?: SchemaOpenApi
+  example?: unknown
+}
+
+export interface RequestBodyOpenApi {
+  $ref?: string
+  description?: string
+  required?: boolean
+  content?: Record<string, MediaTypeOpenApi>
+}
+
+export interface RespostaOpenApi {
+  $ref?: string
+  description?: string
+  content?: Record<string, MediaTypeOpenApi>
+}
+
+export interface OperacaoOpenApi {
+  operationId?: string
+  summary?: string
+  description?: string
+  deprecated?: boolean
+  tags?: string[]
+  parameters?: ParametroOpenApi[]
+  requestBody?: RequestBodyOpenApi
+  responses?: Record<string, RespostaOpenApi>
+  security?: Array<Record<string, string[]>>
+}
+
+export type ItemPathOpenApi = {
+  [M in MetodoHttp]?: OperacaoOpenApi
+} & {
+  /** Parâmetros declarados no path valem para TODAS as operações dele. */
+  parameters?: ParametroOpenApi[]
+  $ref?: string
+}
+
+export interface ServidorOpenApi {
+  url?: string
+  description?: string
+}
+
+export interface TagOpenApi {
+  name?: string
+  description?: string
+}
+
+export interface DocumentoOpenApi {
+  openapi?: string
+  info?: { title?: string; version?: string; description?: string }
+  servers?: ServidorOpenApi[]
+  tags?: TagOpenApi[]
+  paths?: Record<string, ItemPathOpenApi>
+  components?: {
+    schemas?: Record<string, SchemaOpenApi>
+    parameters?: Record<string, ParametroOpenApi>
+    requestBodies?: Record<string, RequestBodyOpenApi>
+    responses?: Record<string, RespostaOpenApi>
+  }
+  /** OpenAPI 2.0 (Swagger) guardava os schemas aqui. */
+  definitions?: Record<string, SchemaOpenApi>
+}
+
+// =============================================================
+// Modelo normalizado — o que a tela realmente consome
+// =============================================================
+
+export interface ParametroNormalizado {
+  nome: string
+  onde: 'query' | 'header' | 'path' | 'cookie'
+  descricao: string
+  obrigatorio: boolean
+  depreciado: boolean
+  schema: SchemaOpenApi
+  /** Tipo já legível: `string`, `integer(int64)`, `array<string>`, `Pessoa`. */
+  tipo: string
+  exemplo: unknown
+  /**
+   * Valores fechados que o campo aceita — vira `<select>` em vez de texto livre.
+   * Sai do `enum` do schema (já resolvido de `$ref`/`allOf`) ou de `boolean`,
+   * que tem só dois valores possíveis. Vazio = campo de texto.
+   *
+   * Os valores vão CRUS, como o servidor espera: `ATIVO`, não "Ativo".
+   * Traduzir aqui quebraria a requisição.
+   */
+  opcoes: string[]
+}
+
+export interface CorpoNormalizado {
+  obrigatorio: boolean
+  descricao: string
+  /** Content-types disponíveis, na ordem da spec. */
+  tiposConteudo: string[]
+  /** Content-type escolhido como padrão (json quando existe). */
+  tipoConteudoPadrao: string
+  schema: SchemaOpenApi | null
+  /** Exemplo gerado a partir do schema, pronto para editar. */
+  exemplo: unknown
+}
+
+export interface RespostaNormalizada {
+  status: string
+  descricao: string
+  tipoConteudo: string | null
+  schema: SchemaOpenApi | null
+  exemplo: unknown
+}
+
+export interface OperacaoNormalizada {
+  /** Chave estável para :key e para deep-link. */
+  id: string
+  metodo: MetodoHttp
+  path: string
+  resumo: string
+  descricao: string
+  depreciada: boolean
+  tags: string[]
+  parametros: ParametroNormalizado[]
+  corpo: CorpoNormalizado | null
+  respostas: RespostaNormalizada[]
+  exigeAutenticacao: boolean
+}
+
+export interface GrupoNormalizado {
+  nome: string
+  descricao: string
+  operacoes: OperacaoNormalizada[]
+}
+
+export interface ApiNormalizada {
+  titulo: string
+  versao: string
+  descricao: string
+  servidores: string[]
+  grupos: GrupoNormalizado[]
+  /** Total de operações, para o cabeçalho da tela. */
+  totalOperacoes: number
+}