# swaggo/fiber-swagger architecture

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

- Interactive diagram: https://gitdiagram.com/swaggo/fiber-swagger
- Repository: https://github.com/swaggo/fiber-swagger

## Overview

##### Project Type and Purpose
-  This is an open-source middleware library (Go module) for the Fiber web framework.
-  Its purpose is to automatically generate and serve Swagger 2.0 API documentation.

##### File Structure
Top-level:
- swagger.go / swagger_test.go – middleware entry point and tests
- example/ – a self-contained example Fiber app showing how to integrate fiber-swagger
– example/main.go – application code mounting the middleware
– example/docs – generated Swagger spec (json, yaml) and Go docs package
- goreleaser.yml, ci workflows – release & CI pipelines

##### Extract Key Architectural Insights from README
-  Build-time step: developer runs `swag init` (Swag CLI) to parse Go comments and generate the `docs` package.
-  Run-time step: application imports both Fiber and fiber-swagger, mounts `fiberSwagger.WrapHandler` at `/swagger/*`, and serves the Swagger UI + json/yaml.

##### Main Components
A. Developer Workspace (SOURCE)
1. application.go + annotated handlers
2. fiber-swagger module (swagger.go)
3. Swag CLI (external tool)
B. Build & Generation Pipeline
1. Developer runs `swag init`
2. Generates `docs/` directory (swagger.json, swagger.yaml, docs.go)
3. `go build` produces the final binary
C. Run-Time Application
1. Fiber HTTP Server
2. fiber-swagger middleware
3. Auto-generated docs package (embedded spec + UI assets)
D. External Actors & Services
1. Web Browser (Developer/Consumer)
2. HTTP requests to `/swagger/*`

##### Relationships and Data Flows
-  **Build-time**:
Source (annotated code) → [Swag CLI] → docs package → go build → binary
-  **Run-time**:
Browser ▶ HTTP GET /swagger/index.html
↳ Fiber server routes request to fiber-swagger handler
↳ Handler serves Swagger UI + loads swagger.json from docs
-  Tests: swagger_test.go calls fiber-swagger functions to verify handler behavior

##### Architectural Patterns & Principles
-  **Middleware pattern**: fiber-swagger sits in the Fiber middleware chain.
-  **Separation of concerns**:
– Code annotations + CLI for spec generation
– HTTP middleware for spec serving
-  **Plug-and-play**: just import and mount; no global state

##### Capturing Essential Elements
-  Don’t forget the **example/main.go** and **example/docs** package—they illustrate intended usage.
-  **swagger.go** (middleware core) and **swagger_test.go** (verifying correct hook behavior).

[Developer Workspace]
└── Annotated Go handlers + import fiber-swagger
└── Swag CLI (external)

[Build Stage]
→ swag init
└── Generated docs/ (json, yaml, doc.go)
→ go build
└── Binary

[Run Stage]
┌──────────────────────────────────────────┐
│  Fiber HTTP Server                      │
│  ┌──────────────┐   ┌────────────────┐  │
│  │ fiber-swagger│◀──│ docs package   │  │
│  │  Middleware   │   │ (swagger.json) │  │
│  └──────────────┘   └────────────────┘  │
└──────────────────────────────────────────┘
▲
│  HTTP GET /swagger/index.html
▼
[Web Browser / Consumer]

[CI/CD & Release]
- .github/workflows/ci.yml
- goreleaser.yml

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Developer Workspace
    subgraph "Developer Workspace"
        direction TB
        Handlers["Annotated Go Handlers"]:::source
        click Handlers "https://github.com/swaggo/fiber-swagger/blob/master/example/main.go"
        Core["fiber-swagger Middleware Core"]:::source
        click Core "https://github.com/swaggo/fiber-swagger/blob/master/swagger.go"
        SwagCLI["Swag CLI"]:::external
        Tests["Middleware Tests"]:::source
        click Tests "https://github.com/swaggo/fiber-swagger/blob/master/swagger_test.go"
    end

    %% Build Stage
    subgraph "Build Stage"
        direction TB
        RunInit["swag init"]:::external
        Docs["Generated Docs Package"]:::generated
        click Docs "https://github.com/swaggo/fiber-swagger/tree/master/example/docs"
        DocsGo["docs.go"]:::generated
        click DocsGo "https://github.com/swaggo/fiber-swagger/blob/master/example/docs/docs.go"
        JSON["swagger.json"]:::generated
        click JSON "https://github.com/swaggo/fiber-swagger/blob/master/example/docs/swagger.json"
        YAML["swagger.yaml"]:::generated
        click YAML "https://github.com/swaggo/fiber-swagger/blob/master/example/docs/swagger.yaml"
        GoBuild["go build"]:::external
        Binary["Compiled Binary"]:::source
    end

    %% Run Stage
    subgraph "Run Stage"
        direction TB
        Browser["Web Browser / Consumer"]:::external
        Server["Fiber HTTP Server"]:::source
        Mid["fiber-swagger Middleware"]:::source
        DocPkg["Docs Package"]:::generated
    end

    %% CI/CD & Release
    subgraph "CI/CD & Release"
        direction TB
        CI["CI Workflow"]:::ci
        click CI "https://github.com/swaggo/fiber-swagger/blob/master/.github/workflows/ci.yml"
        Releaser["GoReleaser"]:::ci
        click Releaser "https://github.com/swaggo/fiber-swagger/blob/master/goreleaser.yml"
        Readme["Project README"]:::source
        click Readme "https://github.com/swaggo/fiber-swagger/blob/master/README.md"
        GoMod["go.mod"]:::source
        click GoMod "https://github.com/swaggo/fiber-swagger/blob/master/go.mod"
        GoSum["go.sum"]:::source
        click GoSum "https://github.com/swaggo/fiber-swagger/blob/master/go.sum"
    end

    %% Build relationships
    Handlers -- "--> parse comments" --> RunInit
    RunInit -- "--> generate docs" --> Docs
    Docs -- "--> include in build" --> GoBuild
    GoBuild -- "--> output" --> Binary
    Core -- "--> tested by" --> Tests

    %% Run relationships
    Browser -- "HTTP GET /swagger/*" --> Server
    Server -- "--> middleware chain" --> Mid
    Mid -- "--> serves UI & JSON" --> DocPkg
    DocPkg -- "--> data for handler" --> Mid
    Mid -- "--> response" --> Server
    Server -- "--> returns UI" --> Browser

    %% Source to runtime link
    Binary -. "built binary contains" .-> Server

    %% Dev to runtime import
    Core -- "imported by app" --> Binary
    Docs -- "embedded docs" --> Binary

    %% Styles
    classDef source fill:#E3F2FD,stroke:#90CAF9,color:#0D47A1
    classDef generated fill:#E8F5E9,stroke:#A5D6A7,color:#1B5E20
    classDef external fill:#FFF3E0,stroke:#FFCC80,color:#E65100
    classDef ci fill:#EDE7F6,stroke:#B39DDB,color:#4A148C
```
