# jellydn/next-swagger-doc architecture

> Architecture diagram of the GitHub repository jellydn/next-swagger-doc, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-01-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jellydn/next-swagger-doc
- Repository: https://github.com/jellydn/next-swagger-doc

## Overview

##### Main Components

a) Core Library Components:
- Swagger Generator Engine (src/swagger.ts)
- CLI Tool (src/cli.ts)
- API Integration Layer (src/index.ts)

b) Integration Components:
- Next.js API Routes
- JSDoc Parser
- Swagger UI Renderer
- File System Interface

**┌─────────────────────────────────────────────────────────────┐**
- Next.js Application                       │
- ┤

- ┌─────────────┐        ┌──────────────────────┐         │
- API Routes  │───────▶│  next-swagger-doc    │         │
- ┘        │                      │         │
- ┌──────────────┐   │         │
- ▼                │   │   Swagger    │   │         │
- ┌─────────────┐       │   │  Generator   │   │         │
- JSDoc     │───────▶   └──────────────┘   │         │
- Comments   │       │          │           │         │
- ┘       │          ▼           │         │
- ┌──────────────┐   │         │
- OpenAPI     │   │         │
- Spec      │   │         │
- ┘   │         │
- ┘         │

- ┌─────────────┐                ▼                      │
- Swagger UI │◀─────── ┌──────────────┐             │
- Component  │         │  API Doc      │             │
- ┘         │    Page      │             │
- ┘             │
- ┘

##### Key Relationships to Highlight

a) Input Flow:
- API Routes contain JSDoc comments
- JSDoc comments are parsed by the generator
- Generator creates OpenAPI specification

b) Output Flow:
- OpenAPI spec is consumed by Swagger UI
- UI renders interactive documentation
- API documentation is served through Next.js pages

##### Implementation Patterns to Emphasize

- Plugin Architecture: Show how the tool integrates with Next.js
- File System Integration: Demonstrate the scanning of API routes
- Documentation Generation Pipeline: JSDoc → Parser → OpenAPI Spec
- Multiple Usage Patterns:
- Static generation
- Dynamic API route
- CLI tool generation

**→ Data/Control Flow**
**⟷ Bidirectional Communication**
**□ Core Components**
**○ External Interfaces**

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph NextApp["Next.js Application"]
        APIRoutes["API Routes"]
        JSDocComments["JSDoc Comments"]
        SwaggerUI["Swagger UI Component"]
        APIDocPage["API Documentation Page"]
        
        subgraph NSWDLib["next-swagger-doc Library"]
            SwaggerGen["Swagger Generator"]
            CLITool["CLI Tool"]
            APIIntegration["API Integration Layer"]
            OpenAPISpec["OpenAPI Specification"]
        end
        
        APIRoutes --> JSDocComments
        JSDocComments --> SwaggerGen
        SwaggerGen --> OpenAPISpec
        OpenAPISpec --> APIDocPage
        APIDocPage --> SwaggerUI
        CLITool --> SwaggerGen
        APIIntegration --> SwaggerGen
    end

    %% Component Styles
    classDef core fill:#2374ab,color:#fff,stroke:#333
    classDef next fill:#4CAF50,color:#fff,stroke:#333
    classDef doc fill:#FF9800,color:#fff,stroke:#333
    classDef external fill:#9E9E9E,color:#fff,stroke:#333

    %% Apply styles
    class SwaggerGen,CLITool,APIIntegration,OpenAPISpec core
    class APIRoutes,NextApp next
    class SwaggerUI,APIDocPage,JSDocComments doc

    %% Click events for component mapping
    click SwaggerGen "https://github.com/jellydn/next-swagger-doc/blob/main/src/swagger.ts"
    click CLITool "https://github.com/jellydn/next-swagger-doc/blob/main/src/cli.ts"
    click APIIntegration "https://github.com/jellydn/next-swagger-doc/blob/main/src/index.ts"
    click APIRoutes "https://github.com/jellydn/next-swagger-doc/tree/main/examples/next13-simple/pages/api/"
    click SwaggerUI "https://github.com/jellydn/next-swagger-doc/blob/main/examples/next13-simple/pages/swagger.tsx"
    click APIDocPage "https://github.com/jellydn/next-swagger-doc/blob/main/examples/next13-simple/pages/api-doc.tsx"
    click OpenAPISpec "https://github.com/jellydn/next-swagger-doc/tree/main/examples/next13-simple/models/openapi/"

    %% Legend
    subgraph Legend
        CoreComp["Core Components"]:::core
        NextComp["Next.js Components"]:::next
        DocComp["Documentation Components"]:::doc
        ExtComp["External Interfaces"]:::external
    end
```
