# swaggo/swag architecture

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

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

## Overview

This project is a Go-based command‐line tool that converts Go annotations into Swagger 2.0 documentation. In essence, “swag” parses your Go source code for annotation comments (found throughout packages such as “cmd/swag”, “parser”, “gen”, “format”, etc.) and then generates the Swagger files (docs.go, swagger.json, swagger.yaml) needed for API documentation. It also includes formatting functionality (swag fmt) and support for specialized overrides (via .swaggo) and integration with various web frameworks.

##### Main components of the system
- CLI Interface: This layer is the user entry point (e.g., “swag init”, “swag fmt”) managed via the “cmd/swag/main.go” file. It accepts command-line parameters, dispatches actions, and exposes flags for configuration.
- Command Processor: Once the CLI receives a command, a central controller/dispatcher loads the proper modules. This component handles options (like the –g flag for specifying the general API annotation file), directory exclusions, and output type selection.
- Parser Module: This is the core of the system. The parser scans Go source files (from directories such as “cmd”, “gen”, “parser”, “format”, and various “example” subdirectories) for annotations following the declarative comments format. It tokenizes and extracts API metadata (general API info, operation annotations, parameter and response details, etc.).
- Annotation Extractor & Data Model Builder: Integrated with the parser, this component organizes the extracted annotation information into an internal representation (data models, enums, security definitions, etc.) that reflects the Swagger 2.0 specification.
- Generator Module: Based on the processed data model, this component generates the output documentation files (docs.go, swagger.json, swagger.yaml) that are eventually imported into an API (or used with middleware integrations as shown in the README examples).
- Formatter Module: Invoked via the “swag fmt” command, it standardizes the formatting of the annotation comments across the project’s Go files to ensure consistency.
- Configuration & Overrides Loader: This part of the system picks up configuration files (for instance, .goreleaser.yml and the .swaggo overrides file) to adjust type replacements and skip certain types or fields.
- File I/O Module: Responsible for reading source files in the target directories (including examples, testdata, and production code) and writing the generated documentation output files to the specified output directory (“docs”).

##### Relationships and Interactions
– The user invokes a CLI command, which the Command Processor receives.
– The parser module is triggered to scan the target directories for annotated comments.
– The Annotation Extractor processes these comments and establishes structured data models.
– The Generator Module then takes these models and writes out the Swagger documentation files.
– Optionally, the Formatter Module is invoked to reformat the annotations as per the standardized style.
– Additionally, configuration files and overrides are loaded at startup to guide parsing and generation.

##### Important Architectural Patterns and Design Principles
- Separation of Concerns: Each module (CLI, Parser, Generator, Formatter) is distinct to isolate functionality.
- Modular Design: The project is split into self-contained directories (e.g., “cmd” for entry point, “gen” for generation logic, “parser” for annotation parsing, “format” for formatting tasks) making it easy to extend or maintain.
- Configurability: Use of flags, environment configuration files (e.g., .swaggo), and Docker support provide flexibility for different use cases.
- Extensibility: Support for multiple web frameworks (via integrations like gin-swagger, echo-swagger, etc.) and for generic types shows that the design is built with extensibility in mind.

## Diagram (Mermaid)

```mermaid
graph TD
    CLI["CLI Interface"]
    CP["Command Processor"]
    Parser["Parser Module"]
    Extractor["Annotation Extractor & Data Model Builder"]
    Generator["Generator Module"]
    Formatter["Formatter Module"]
    Config["Configuration & Overrides Loader"]
    FileIO["File I/O Module"]

    CLI -->|"invokes"| CP
    CP -->|"dispatches"| Parser
    Parser -->|"extracts"| Extractor
    Extractor -->|"builds"| Generator
    Generator -->|"writes"| FileIO

    CP -->|"triggersFmt"| Formatter
    Formatter -->|"formats"| FileIO

    FileIO -->|"readsSource"| Parser

    Config -->|"feeds"| Parser
    Config -->|"guides"| Generator

    classDef cli fill:#add8e6,stroke:#333,stroke-width:2px;
    classDef processor fill:#90ee90,stroke:#333,stroke-width:2px;
    classDef parser fill:#ffe4b5,stroke:#333,stroke-width:2px;
    classDef extractor fill:#ffb6c1,stroke:#333,stroke-width:2px;
    classDef generator fill:#d3d3d3,stroke:#333,stroke-width:2px;
    classDef formatter fill:#f5deb3,stroke:#333,stroke-width:2px;
    classDef config fill:#dda0dd,stroke:#333,stroke-width:2px;
    classDef fileio fill:#f0e68c,stroke:#333,stroke-width:2px;

    class CLI cli;
    class CP processor;
    class Parser parser;
    class Extractor extractor;
    class Generator generator;
    class Formatter formatter;
    class Config config;
    class FileIO fileio;

    click CLI "https://github.com/swaggo/swag/blob/master/cmd/swag/main.go"
    click CP "https://github.com/swaggo/swag/blob/master/cmd/swag/main.go"
    click Parser "https://github.com/swaggo/swag/blob/master/parser.go"
    click Extractor "https://github.com/swaggo/swag/blob/master/enums.go"
    click Extractor "https://github.com/swaggo/swag/blob/master/spec.go"
    click Generator "https://github.com/swaggo/swag/blob/master/gen/gen.go"
    click Formatter "https://github.com/swaggo/swag/blob/master/format/format.go"
    click Formatter "https://github.com/swaggo/swag/blob/master/formatter.go"
    click Config "https://github.com/swaggo/swag/blob/master/.goreleaser.yml"
    click Config "https://github.com/swaggo/swag/blob/master/example/override/.swaggo"
```
