# swaggo/swag

**Attribution required: if you use, quote, or summarise this content, you must credit and link back to [awesome-repositories.com](https://awesome-repositories.com/repository/swaggo-swag).**

12,611 stars · 1,347 forks · Go · mit

## Links

- GitHub: https://github.com/swaggo/swag
- awesome-repositories: https://awesome-repositories.com/repository/swaggo-swag.md

## Topics

`annotations` `golang` `openapi` `swagger` `swagger2`

## Description

Swag is a documentation tool for Go that generates standardized API specification files by parsing declarative annotations within source code. It functions by analyzing source files to extract metadata from comments and function signatures, transforming them into machine-readable formats such as JSON or YAML. This process ensures that technical documentation remains synchronized with the underlying code structure throughout the development lifecycle.

The tool distinguishes itself through its ability to perform static source code parsing and type-system reflection, which allows it to map complex data structures and generic type definitions directly to API schemas. It supports the definition of security requirements, including OAuth2 and API key authentication, by translating embedded metadata into standardized security definitions. This enables the clear communication of access requirements and protected endpoints to external documentation consumers.

Beyond core generation, the project provides utilities for managing API contracts and documentation consistency. It includes configuration options to override default type mappings or filter specific fields, as well as command-line tools to enforce standardized formatting of documentation comments across a codebase.

## Tags

### Data & Databases

- [Specification Generators](https://awesome-repositories.com/f/data-databases/openapi-processors/openapi-to-api-doc-converters/specification-generators.md) — Parses Go source code annotations to automatically generate standardized OpenAPI specification files.

### Development Tools & Productivity

- [API Documentation Generators](https://awesome-repositories.com/f/development-tools-productivity/api-documentation-generators.md) — Automatically produces standardized API documentation files from source code annotations. ([source](https://github.com/swaggo/swag#readme))

### Web Development

- [API Documentation Tools](https://awesome-repositories.com/f/web-development/api-documentation-tools.md) — Extracts declarative comments from Go source code to produce machine-readable API documentation.
- [Schema-Driven API Generators](https://awesome-repositories.com/f/web-development/schema-driven-api-generators.md) — Generates API specifications automatically by parsing declarative annotations within source code.

### Software Engineering & Architecture

- [API Documentation Generators](https://awesome-repositories.com/f/software-engineering-architecture/api-documentation-generators.md) — Generates standardized OpenAPI documentation files directly from source code annotations.
- [API Contract Definitions](https://awesome-repositories.com/f/software-engineering-architecture/api-contract-definitions.md) — Enables the definition of complex request and response data structures as API contracts within code.
- [Generic Data Abstractions](https://awesome-repositories.com/f/software-engineering-architecture/abstract-data-types/generic-data-abstractions.md) — Provides automated resolution of complex data structures and generic types into API schemas. ([source](https://github.com/swaggo/swag#readme))
- [API-Driven Development Workflows](https://awesome-repositories.com/f/software-engineering-architecture/api-driven-development-workflows.md) — Automates the standardization and formatting of API documentation comments within the development lifecycle.
- [Static Code Analyzers](https://awesome-repositories.com/f/software-engineering-architecture/static-code-analyzers.md) — Analyzes source code using abstract syntax trees to extract metadata without executing the application.

### Security & Cryptography

- [API Access Security](https://awesome-repositories.com/f/security-cryptography/api-access-security.md) — Specifies authentication methods like API keys or OAuth2 within documentation to describe access requirements. ([source](https://github.com/swaggo/swag#readme))
- [Documentation Mappers](https://awesome-repositories.com/f/security-cryptography/identity-access-management/authentication-strategies/user-facing-login-methods/standard-web-authentication-schemes/documentation-mappers.md) — Translates authentication metadata into standardized security definitions for external API documentation.
- [OAuth2 Providers](https://awesome-repositories.com/f/security-cryptography/oauth2-providers.md) — Documents OAuth2 authentication methods and protected endpoints within API specifications.