Skip to content

@fc/swagger-nuxt-module ​

Módulo Nuxt especializado em Swagger / OpenAPI. Concentra-se em duas responsabilidades:

  • gerar specs (individual e opcionalmente agregada por namespace) a partir de blocos @swagger e tipos TypeScript, com validação de referências e diagnóstico detalhado;
  • fornecer o componente <SwaggerUi /> — um wrapper genérico em torno do swagger-ui como componente Vue 3 reativo, com estilos compatíveis com modo escuro.

Toda a UI de portal (landing page, cabeçalho, cards, alternador de tema, tokens visuais) é de responsabilidade da aplicação que consome o módulo (ex.: @fc/docs-api).

Instalação ​

bash
pnpm add @fc/swagger-nuxt-module

Configuração básica ​

ts
export default defineNuxtConfig({
  modules: ['@fc/swagger-nuxt-module'],
  swagger: {
    info: {
      title: 'Minha API',
      description: 'Descrição da API.',
      version: '1.0.0',
    },
    apis: ['./server/routes/**/*.ts'],
    routes: {
      json: '/_openapi.json',
      ui: '/_swagger',
    },
    uiDisponibilidade: 'dev-local',
    // Opcional e sem default: declare um scheme apenas se alguma operação for
    // referenciá-lo no `@swagger`. A proteção estrutural por chave de API não
    // precisa disto: o gerador e o runtime a derivam de `apiPublica.apiKey`.
    securitySchemes: {
      ApiKeyAuth: {
        type: 'apiKey',
        in: 'header',
        name: 'x-api-key',
      },
    },
    types: [
      {
        name: 'MinhaRespostaApi',
        src: './server/utils/tipos.ts',
      },
    ],
  },
})

Agregação por namespace ​

Na app hospedeira, adicione swagger.agregador. Cada documento agregado informa o id, o conteúdo exibido e as fontes de onde os paths serão lidos.

ts
export default defineNuxtConfig({
  modules: ['@fc/swagger-nuxt-module'],
  swagger: {
    info: { title: 'Portal', description: '...', version: '1.0.0' },
    apis: [],
    agregador: {
      documentos: [
        {
          id: 'rgps',
          titulo: 'RGPS',
          descricao: 'Endpoints previdenciários públicos.',
          fontes: [
            { app: '../prev-api', prefixosPath: ['/rgps/api/v1/', '/api/v1/'] },
            { app: '../rmi-api', prefixosPath: ['/rgps/api/v1/'] },
          ],
        },
      ],
    },
  },
})

O núcleo puro usado nessa agregação também é uma superfície pública para runtimes de servidor:

ts
import { agregarDocumentoSwagger } from '@fc/swagger-nuxt-module/agregador'

Ele aplica a mesma filtragem e validação do CLI, rejeitando colisões de path, schema e securityScheme, além de $ref interno quebrado. A ordem das fontes não altera o documento produzido nem o diagnóstico.

Metadados de um mesmo PathItem (parameters, $ref, servers, summary e description) só podem reaparecer com conteúdo estruturalmente idêntico. Conteúdo divergente falha com diagnóstico estável, em vez de depender da ordem das fontes.

Componente <SwaggerUi /> ​

O módulo registra globalmente o componente SwaggerUi, que embute o Swagger UI num iframe da mesma origem. A página do iframe é servida pelo próprio módulo (rota /_swagger-visualizador, sempre registrada) com o swagger-ui-dist self-hosted (assets em /_swagger-ui/) e uma folha que o veste com a linguagem da Fábrica de Cálculos. Nada do Swagger UI entra no bundle da aplicação: não há React no grafo de dependências, e o CSS do Swagger não convive com o da aplicação. Props:

  • urlSpec — caminho da spec na mesma origem (a página recusa URL absoluta com 400: ela é pública, e aceitar qualquer URL a tornaria um visualizador aberto para specs de terceiros);
  • tema — 'claro' | 'escuro'; a troca é aplicada ao iframe sem recarregar;
  • persistirAutorizacao — guarda a autorização (x-api-key) no localStorage do navegador; só por opção explícita de quem usa;
  • baseUrl — o baseURL da aplicação, para compor a rota da página.

Eventos emitidos:

  • pronto(instancia) — o Swagger UI terminou de carregar; a instância é o window.ui da página do iframe (mesma origem), com layoutActions.updateFilter e specActions;
  • hash(hash) — o link direto por operação mudou (deepLinking); quem hospeda decide como espelhá-lo na própria URL;
  • erro(erro) — a página sinalizou prontidão sem expor a instância.

O iframe cresce com o conteúdo (a página publica a altura por postMessage, restrito à própria origem): quem rola é a página hospedeira, e âncoras e busca do navegador funcionam sobre uma rolagem só.

Exemplo mínimo:

vue
<script setup lang=ts>
const config = useRuntimeConfig()
const urlSpec = '/_swagger/specs/principal.json'
</script>

<template>
  <SwaggerUi :url-spec=urlSpec tema=escuro :base-url=config.app.baseURL />
</template>

Modo escuro ​

A página do iframe usa a classe dark-mode no <html> — a mesma que o Swagger UI conhece — e a folha da Fábrica redefine os tokens sob ela. Não há folha separada de tema escuro.

Extensões ​

O módulo não injeta plugins no Swagger UI nem expõe o store dele. O que a aplicação hospedeira precisa (filtros por tag, por exemplo) é feito de fora, pela instância entregue em pronto.

CLI ​

O módulo expõe dois binários:

  • generate-swagger-spec — lê a configuração swagger da app atual e grava apenas a spec individual em ./.swagger/principal.json (ou no caminho informado via --out). Uso típico em apps que expõem sua própria OpenAPI (ex.: prev-api, rmi-api, backoffice).
  • generate-swagger-spec-agregado — executa fluxo completo: gera a spec principal, gera uma spec por documento configurado em swagger.agregador e emite o manifest.json. Uso típico no app hospedeiro do portal (ex.: docs-api).
bash
generate-swagger-spec
generate-swagger-spec --out ./public/_swagger/specs/principal.json
generate-swagger-spec-agregado

Estrutura gerada pelo binário agregado (em public/_swagger/ por padrão):

  • specs/principal.json: spec agregada com todos os endpoints do portal;
  • specs/<id>.json: spec por documento configurado (ex.: specs/rgps.json);
  • manifest.json: manifesto dos documentos, com URLs relativas (./specs/<id>.json).

O gerador aplica aos artefatos estáticos a configuração estrutural de apiPublica.apiKey: declara ApiKeyAuth e inclui o requisito nas operações cujos paths são protegidos. Requisitos security escritos manualmente no OpenAPI são preservados. Se uma operação já exige outra credencial, ApiKeyAuth entra no mesmo objeto do requisito, de modo que os controles sejam conjuntos, não alternativas.

O diretório dos artefatos é sempre public/_swagger/; configurar outro valor em swagger.artefatos.diretorio é rejeitado antes de qualquer escrita. IDs de documento aceitam somente letras minúsculas, números e hífens, sem repetição. A publicação é atômica e o gerador só substitui uma saída identificada pelo marcador interno .fc-swagger. Ao migrar uma saída antiga ainda sem marcador, remova apenas public/_swagger/ uma vez e execute novamente o comando.

Runtime ​

Após executar spec:gen, a app expõe:

  • /_openapi.json: handler dinâmico com a spec individual e servers derivados da requisição atual (registrado pelo módulo);
  • /_swagger/specs/*.json, /_swagger/manifest.json: servidos estaticamente por public/_swagger/ via Nitro.

O contrato público canônico é /_openapi.json. O arquivo principal.json é somente a base imutável produzida no build: o runtime o lê e interpreta uma vez por processo, cria uma cópia independente para cada requisição e então aplica origem, autenticação e schemas do envelope de erro PDPJ. Essa cópia evita que dados derivados de um host ou de uma configuração contaminem a resposta seguinte. Rotas dos namespaces internos não entram no contrato gerado nem no documento servido.

Como a resposta depende da origem e da configuração em execução, /_openapi.json usa Cache-Control: no-store. Se a base não puder ser carregada, o consumidor recebe uma mensagem estável, sem caminho de arquivo ou detalhe do sistema; o diagnóstico completo fica restrito ao log do servidor.

A UI (landing, visualizador, rotas /_swagger e /_swagger/:documento) fica por conta da aplicação.

O runtime público recebe somente info, routes e uiDisponibilidade, usados pela UI automática. Globs, tipos, fontes do agregador, schemes e caminhos de geração não são serializados no payload do cliente. O handler OpenAPI usa diretamente o diretório padrão compartilhado com o gerador.

Em runtime, a proteção é recalculada a partir da configuração efetiva sem alterar o artefato estático. Assim, uma execução local com a chave desativada pode retirar a anotação estrutural da resposta dinâmica, enquanto o arquivo de build permanece íntegro. Quando uma operação já exige autenticação e seu path também exige chave de API, o transformador inclui ApiKeyAuth no mesmo requisito. Em OpenAPI isso significa que os dois controles são obrigatórios; objetos separados no array significariam alternativas e publicariam incorretamente “um ou outro”.

UI automática (/_swagger) ​

Quando uiAutomatica não é desativado, o módulo serve em routes.ui a página autônoma do Swagger UI — a mesma página do componente, sem a folha da Fábrica e sem a ponte com um hospedeiro — com os assets self-hosted do swagger-ui-dist, publicados pelo módulo em /_swagger-ui/. Não há dependência de CDN. Se os scripts não carregarem (proxy corporativo, CSP restritiva) ou o Swagger UI não inicializar em 8 s, a página mostra um painel de erro com o link para o JSON bruto.

Disponibilidade da UI automática ​

Use uiDisponibilidade para controlar quando a rota routes.ui deve responder:

  • sempre — comportamento legado; publica a UI em qualquer ambiente.
  • dev — publica apenas quando a aplicação está em modo de desenvolvimento.
  • dev-local — publica apenas em desenvolvimento local e host local (localhost, 127.0.0.1, ::1).

Fora do contexto permitido, a rota responde 404. Esse é o modo recomendado para apps que usam docs-api como portal público e querem manter /_swagger apenas como ferramenta local.

Diagnóstico de erros ​

O gerador falha com relatório consolidado quando encontra problemas como:

  • YAML/JSDoc inválido em blocos @swagger;
  • tipo raiz ausente ou schema TypeScript não serializável;
  • $ref interno quebrado;
  • securityScheme referenciado, mas não declarado;
  • conflito de path + method, metadado de PathItem, schema ou securityScheme durante agregação.

O relatório sempre aponta app, arquivo, tipo e trecho relevante para correção.