# swaggo/echo-swagger architecture

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

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

## Overview

##### Project type and purpose
- It’s a Go “middleware library” (not a standalone full-stack app) for the Echo web framework.
- Purpose: at build time it uses the Swag CLI to parse Go source comments and generate `docs` (Go files + JSON/YAML). At runtime it mounts an HTTP handler (`/swagger/*`) that serves the generated Swagger UI and spec.

##### File structure
Top-level:
- `swagger.go` & `swagger_test.go` – core middleware implementation and tests
- `go.mod`/`go.sum` – Go modules
- `example/v2` & `example/v3` – sample Echo apps (OAS2 & OAS3) each containing:
– `main.go` (imports echo-swagger and generated docs)
– `docs/` (auto-generated by `swag init`)
- CI config, GitHub workflows, release tooling (goreleaser), templates, etc.

##### README for additional insights
- Dependencies: `github.com/swaggo/swag/cmd/swag` (“Swag CLI”), Echo v4, echo-swagger itself.
- Workflow:
a) Developer annotates API in Go with special comments.
b) Runs `swag init` → produces `docs/` folder (`doc.go`, `swagger.json`, `.yaml`).
c) Imports `github.com/swaggo/echo-swagger`.
d) In Echo app: `e.GET("/swagger/*", echoSwagger.WrapHandler)` (or `WrapHandlerV3`).
e) Client browses to `/swagger/index.html`.

## Diagram (Mermaid)

```mermaid
flowchart TB
  %% Design & Build Time
  subgraph "Design & Build Time"
    Developer["Developer"]:::external
    SwagCLI["Swag CLI\n(github.com/swaggo/swag)"]:::genTime
    DocsGen["Generated Docs\n(example/v2/docs/, example/v3/docs/)"]:::code
    CoreLib["Core Middleware Library\n(swagger.go)"]:::code
    CoreLibTests["Core Middleware Tests\n(swagger_test.go)"]:::code
    GoMod["Go Module Definition\n(go.mod)"]:::code

    Developer -->|"annotates & runs"| SwagCLI
    SwagCLI -->|"generates docs"| DocsGen
    DocsGen -->|"populates"| ExV2Docs
    DocsGen -->|"populates"| ExV3DocsGo
    Developer -->|"edits module"| GoMod
    GoMod -->|"defines deps"| CoreLib
  end

  %% Examples
  subgraph "Example Applications"
    subgraph "v2 (OAS2) Example"
      ExV2Main["Main App\n(example/v2/main.go)"]:::code
      ExV2Docs["Docs v2\n(example/v2/docs/docs.go)"]:::code
    end
    subgraph "v3 (OAS3) Example"
      ExV3Main["Main App\n(example/v3/main.go)"]:::code
      ExV3DocsGo["Docs v3 Go\n(example/v3/docs/docs.go)"]:::code
      ExV3JSON["JSON Spec\n(example/v3/docs/swagger.json)"]:::code
      ExV3YAML["YAML Spec\n(example/v3/docs/swagger.yaml)"]:::code
    end

    ExV2Main -->|"imports"| CoreLib
    ExV3Main -->|"imports"| CoreLib
    ExV3DocsGo --> ExV3JSON
    ExV3DocsGo --> ExV3YAML
  end

  %% CI/CD & Release
  subgraph "CI/CD & Release"
    CI["CI Workflow\n(.github/workflows/ci.yml)"]:::genTime
    Release["Release Config\n(.goreleaser.yml)"]:::genTime

    CI -->|"runs tests & swag init"| SwagCLI
    CI -->|"triggers"| Release
  end

  %% Runtime
  subgraph "Runtime"
    Browser["HTTP Client (Browser)"]:::external
    EchoServer["Echo Web Server"]:::runtime
    Middleware["echo-swagger Middleware"]:::runtime
    SwaggerUI["Swagger UI Static Assets"]:::external
    DocsRuntime["Docs (JSON/YAML)"]:::runtime

    Browser -->|"GET /swagger/index.html"| EchoServer
    EchoServer -->|"routes to"| Middleware
    Middleware -->|"serves UI + spec"| Browser
    Middleware -->|"loads"| DocsRuntime
    Middleware -->|"embeds"| SwaggerUI
  end

  %% Click Events
  click CoreLib "https://github.com/swaggo/echo-swagger/blob/master/swagger.go"
  click CoreLibTests "https://github.com/swaggo/echo-swagger/blob/master/swagger_test.go"
  click GoMod "https://github.com/swaggo/echo-swagger/blob/master/go.mod"
  click ExV2Main "https://github.com/swaggo/echo-swagger/blob/master/example/v2/main.go"
  click ExV2Docs "https://github.com/swaggo/echo-swagger/blob/master/example/v2/docs/docs.go"
  click ExV3Main "https://github.com/swaggo/echo-swagger/blob/master/example/v3/main.go"
  click ExV3DocsGo "https://github.com/swaggo/echo-swagger/blob/master/example/v3/docs/docs.go"
  click ExV3JSON "https://github.com/swaggo/echo-swagger/blob/master/example/v3/docs/swagger.json"
  click ExV3YAML "https://github.com/swaggo/echo-swagger/blob/master/example/v3/docs/swagger.yaml"
  click CI "https://github.com/swaggo/echo-swagger/blob/master/.github/workflows/ci.yml"
  click Release "https://github.com/swaggo/echo-swagger/blob/master/.goreleaser.yml"

  %% Styles
  classDef genTime fill:#cce5ff,stroke:#333,stroke-width:1px
  classDef runtime fill:#d4edda,stroke:#333,stroke-width:1px
  classDef external fill:#e2e3e5,stroke:#333,stroke-width:1px
  classDef code fill:#fff3cd,stroke:#333,stroke-width:1px
```
