swagger-ui

Swagger UI Documentation Viewer

Uma aplicação React moderna para visualização e teste de APIs através de documentação Swagger/OpenAPI.

📊 Arquitetura do Sistema

flowchart TB
    subgraph Frontend
        UI[SwaggerUI Component]
        Router[React Router]
        State[State Management]
    end
    
    subgraph Core
        Parser[OpenAPI Parser]
        Validator[Schema Validator]
        Mock[Mock Service]
    end
    
    subgraph External
        API[Real API]
        Docs[OpenAPI Specs]
    end
    
    UI --> Router
    Router --> State
    State --> Parser
    Parser --> Validator
    Parser --> Mock
    Mock --> API
    Docs --> Parser
    
    style Frontend fill:#e1f5fe
    style Core fill:#fff3e0
    style External fill:#f1f8e9

Loading

🔄 Fluxo de Requisições

sequenceDiagram
    participant U as Usuário
    participant UI as Interface
    participant P as Parser
    participant M as Mock Service
    participant A as API Real

    U->>UI: Seleciona Endpoint
    UI->>P: Processa Spec
    P->>UI: Retorna Metadata
    U->>UI: Executa Requisição
    
    alt Modo Mock
        UI->>M: Envia Requisição
        M->>UI: Retorna Dados Mock
    else Modo Produção
        UI->>A: Envia Requisição
        A->>UI: Retorna Dados Reais
    end
    
    UI->>U: Exibe Resultado

Loading

📁 Estrutura do Projeto

graph TD
    A[swagger-ui] --> B[src]
    A --> C[public]
    A --> D[config]
    
    B --> E[components]
    B --> F[hooks]
    B --> G[utils]
    
    E --> H[ApiEndpoint]
    E --> I[Documentation]
    E --> J[Layout]
    E --> K[SwaggerUI]
    
    D --> L[webpack.config.js]
    D --> M[jest.config.js]
    
    style A fill:#e1f5fe
    style B fill:#fff3e0
    style C fill:#f1f8e9
    style D fill:#fff3e0

Loading

🚀 Funcionalidades

• 📚 Visualização interativa de documentação Swagger/OpenAPI
• 🔍 Exploração de endpoints da API
• 🧪 Interface para testar chamadas à API
• 📱 Design responsivo
• 🎨 Interface moderna com Tailwind CSS
• 🔄 Simulação de chamadas à API com dados mock
• 🌐 Suporte a múltiplos formatos de especificação OpenAPI
• 🔒 Suporte a autenticação e autorização
• 📊 Visualização de esquemas de dados

🔄 Ciclo de Vida da Requisição

stateDiagram-v2
    [*] --> ValidaçãoEntrada
    ValidaçãoEntrada --> ProcessamentoSpec
    ProcessamentoSpec --> PreparaçãoRequisição
    
    PreparaçãoRequisição --> ModeMock: Mock Ativado
    PreparaçãoRequisição --> ModeProduction: Mock Desativado
    
    ModeMock --> GeraçãoResposta
    ModeProduction --> ChamadaAPI
    ChamadaAPI --> ProcessamentoResposta
    
    GeraçãoResposta --> ExibiçãoResultado
    ProcessamentoResposta --> ExibiçãoResultado
    
    ExibiçãoResultado --> [*]

Loading

📋 Pré-requisitos

• Node.js (versão 14 ou superior)
• npm (gerenciador de pacotes do Node.js)

🛠️ Instalação

1. Clone o repositório:

git clone https://github.com/govinda777/swagger-ui.git
cd swagger-ui

2. Instale as dependências:

npm install -g serve --registry=https://registry.npmjs.org/
npm install --registry=https://registry.npmjs.org/
npm install --save-dev @babel/preset-react @babel/preset-env --registry=https://registry.npmjs.org/

3. Inicie o servidor de desenvolvimento:

npm start

🔧 Configuração

Fluxo de Configuração

graph LR
    A[Inicialização] --> B[Carrega .env]
    B --> C[Configura Cliente]
    C --> D[Inicializa Parser]
    D --> E[Configura Rotas]
    E --> F[Prepara UI]
    
    style A fill:#f9f9f9
    style B fill:#e1f5fe
    style C fill:#fff3e0
    style D fill:#f1f8e9
    style E fill:#fce4ec
    style F fill:#f3e5f5

Loading

Configuração da API

export const swaggerSpec = {
  openapi: "3.0.0",
  info: {
    title: "Sua API",
    version: "1.0.0",
    description: "Descrição da sua API"
  },
  servers: [
    {
      url: "https://api.exemplo.com",
      description: "Servidor de Produção"
    }
  ],
  paths: {
    // Seus endpoints aqui
  }
};

🎨 Personalização do Estilo

module.exports = {
  theme: {
    extend: {
      colors: {
        primary: {
          light: '#4FD1C5',
          DEFAULT: '#38B2AC',
          dark: '#319795',
        },
      },
      fontFamily: {
        sans: ['Inter', 'sans-serif'],
      },
    },
  },
  plugins: [
    require('@tailwindcss/forms'),
    require('@tailwindcss/typography'),
  ],
};

📝 Scripts Disponíveis

• npm start: Inicia o servidor de desenvolvimento
• npm run build: Cria uma build de produção
• npm test: Executa os testes
• npm run lint: Verifica o código com ESLint
• npm run format: Formata o código com Prettier

🧪 Processo de Teste

graph TD
    A[Início Teste] --> B[Testes Unitários]
    B --> C[Testes de Integração]
    C --> D[Testes E2E]
    D --> E[Cobertura]
    E --> F[Relatório]
    
    style A fill:#f9f9f9
    style B fill:#e1f5fe
    style C fill:#fff3e0
    style D fill:#f1f8e9
    style E fill:#fce4ec
    style F fill:#f3e5f5

Loading

Execute os testes com:

npm test

Para cobertura de testes:

npm test -- --coverage

🤝 Fluxo de Contribuição

gitGraph
    commit id: "initial"
    branch feature
    checkout feature
    commit id: "feature-1"
    commit id: "feature-2"
    checkout main
    merge feature
    commit id: "release"

Loading

1. Faça um fork do projeto
2. Crie sua branch de feature (git checkout -b feature/AmazingFeature)
3. Commit suas mudanças (git commit -m 'Add: nova funcionalidade incrível')
4. Push para a branch (git push origin feature/AmazingFeature)
5. Abra um Pull Request

📄 Licença

Este projeto está sob a licença MIT. Veja o arquivo LICENSE para mais detalhes.

✨ Exemplos

Configuração Básica

import SwaggerUI from './components/SwaggerUI';

function App() {
  return (
    <SwaggerUI 
      spec={swaggerSpec}
      options={{
        deepLinking: true,
        defaultModelsExpandDepth: 1,
        defaultModelExpandDepth: 1,
      }}
    />
  );
}

Uso com Autenticação

<SwaggerUI 
  spec={swaggerSpec}
  authConfig={{
    type: 'bearer',
    token: 'seu-token-aqui'
  }}
/>

🐛 Processo de Report de Bugs

graph TD
    A[Identificar Bug] --> B[Criar Issue]
    B --> C[Reproduzir]
    C --> D[Investigar]
    D --> E[Corrigir]
    E --> F[Testar]
    F --> G[Merge]
    
    style A fill:#f9f9f9
    style B fill:#e1f5fe
    style C fill:#fff3e0
    style D fill:#f1f8e9
    style E fill:#fce4ec
    style F fill:#f3e5f5
    style G fill:#e8eaf6

Loading

Ao reportar um bug, inclua:

1. Como reproduzir o problema
2. O que era esperado
3. O que aconteceu
4. Screenshots (se aplicável)
5. Ambiente (navegador, OS, etc)

Arquitetura do Projeto

• App.js: Componente principal da aplicação que renderiza o componente SwaggerUI.
• SwaggerUI.js: Componente responsável por renderizar a interface do Swagger.

Configuração do Webpack

A aplicação utiliza três arquivos de configuração do Webpack:

• webpack.common.js: Contém a configuração comum usada tanto em desenvolvimento quanto em produção.
• webpack.dev.js: Configuração específica para o ambiente de desenvolvimento.
• webpack.prod.js: Configuração específica para o ambiente de produção.

Scripts do NPM

• start: Inicia o servidor de desenvolvimento.
• build: Gera o build de produção.
• test: Executa os testes unitários com cobertura.
• predeploy: Gera o build de produção antes do deploy.
• deploy: Faz o deploy da aplicação para o GitHub Pages.

Testes

Os testes são escritos utilizando o Jest e o React Testing Library. Os arquivos de teste estão localizados no mesmo diretório dos componentes que eles testam e seguem o padrão *.test.js.

Estilo

A aplicação utiliza o Tailwind CSS para estilização. Os estilos são processados pelo PostCSS através do postcss-loader no Webpack.

Deploy

O deploy da aplicação é feito automaticamente para o GitHub Pages utilizando o GitHub Actions. O workflow de deploy está configurado no arquivo .github/workflows/deploy.yml.

Para suporte, entre em contato através das issues do GitHub ou envie um email para [[email protected]]

How to deploy local?

chmod +x local-deploy.sh

📞 Suporte

Para suporte, entre em contato através das issues do GitHub ou envie um email para [[email protected]]