🚀

Live Infrastructure Docs

LIVE

You're using this Go application right now. Explore the real infrastructure powering your experience.

📖 REST API Documentation

Auto-generated Swagger documentation with interactive testing for all API endpoints

Interactive API Documentation

🎯 What is Swagger?

Swagger (now OpenAPI) is a specification for describing REST APIs. It provides a standard way to document your API endpoints, request/response formats, and allows developers to interact with your API directly from a web interface.

• Interactive Testing: Try API calls directly from the browser
• Auto-Generated: Documentation stays synchronized with your code
• Schema Validation: Ensures requests match expected formats
• Code Generation: Generate client SDKs in multiple languages

🚀 Live API Access

Click the link below to access the interactive Swagger UI where you can explore and test all available endpoints:

https://majesticcoding.com/swagger/index.html

📊 Available Endpoints

GitHub Integration

GET /api/github/{username}

Fetch profile, repos, and stats

Twitch Analytics

GET /api/twitch/analytics

Live streaming metrics

YouTube Stats

GET /api/youtube/stats

Channel and video statistics

Platform Metrics

GET /api/metrics

Aggregated platform data

🔧 How to Use Swagger UI

Browse Endpoints: Click on any endpoint to see details
Try it Out: Click "Try it out" button to test the endpoint
Enter Parameters: Fill in required path or query parameters
Execute: Click "Execute" to make the actual API call
View Response: See the real response data and HTTP status
Copy as cURL: Get command-line examples for integration

💡 Pro Tips

• Use the Models section to understand response schemas

• Check Response Examples to see expected data formats

• Look for HTTP status codes to understand error handling

• Copy the Request URL for use in your applications

Swagger Annotations

// GitHub API endpoint with full annotations
// @Summary Get GitHub Profile
// @Description Fetches comprehensive GitHub data for a username
// @Tags GitHub
// @Accept json
// @Produce json
// @Param username path string true "GitHub username"
// @Success 200 {object} models.GitHubProfile
// @Failure 400 {object} models.ErrorResponse
// @Failure 404 {object} models.ErrorResponse
// @Failure 500 {object} models.ErrorResponse
// @Router /api/github/{username} [get]
func GetGitHubProfile(c *gin.Context) {
    username := c.Param("username")
    profile, err := services.FetchGitHubData(username)
    if err != nil {
        c.JSON(404, models.ErrorResponse{
            Error:   "User not found",
            Message: "GitHub user does not exist",
        })
        return
    }
    c.JSON(200, profile)
}

// Twitch analytics endpoint
// @Summary Get Twitch Analytics
// @Description Retrieve Twitch channel statistics and analytics
// @Tags Twitch
// @Accept json
// @Produce json
// @Param channel query string false "Twitch channel name"
// @Success 200 {object} models.TwitchAnalytics
// @Failure 429 {object} models.ErrorResponse "Rate limit exceeded"
// @Router /api/twitch/analytics [get]
func GetTwitchAnalytics(c *gin.Context) {
    // Implementation here
}

// YouTube stats endpoint
// @Summary Get YouTube Channel Stats
// @Description Fetch subscriber count and video statistics
// @Tags YouTube
// @Success 200 {object} models.YouTubeStats
// @Router /api/youtube/stats [get]
func GetYouTubeStats(c *gin.Context) {
    // Implementation here
}

API Handlers Implementation

// GitHub profile handler with error handling
func GetGitHubProfile(c *gin.Context) {
    username := c.Param("username")

    // Validate input
    if username == "" {
        c.JSON(400, gin.H{
            "error": "username is required",
            "code":  "MISSING_USERNAME",
        })
        return
    }

    // Fetch data from GitHub API
    profile, err := services.FetchGitHubData(username)
    if err != nil {
        log.Printf("GitHub API error for user %s: %v", username, err)
        c.JSON(500, gin.H{
            "error":   "Failed to fetch GitHub data",
            "message": err.Error(),
        })
        return
    }

    // Return successful response
    c.Header("Cache-Control", "public, max-age=300") // 5 min cache
    c.JSON(200, profile)
}

// Real-time metrics endpoint
func GetMetrics(c *gin.Context) {
    metrics := gin.H{
        "github": gin.H{
            "followers":     1250,
            "repositories":  45,
            "stars":        892,
        },
        "youtube": gin.H{
            "subscribers":   129000,
            "views":        1500000,
            "videos":       180,
        },
        "twitch": gin.H{
            "followers":     8500,
            "avg_viewers":   125,
            "streams":       340,
        },
        "timestamp": time.Now().UTC(),
    }

    c.JSON(200, metrics)
}

// Health check endpoint
func HealthCheck(c *gin.Context) {
    status := gin.H{
        "status":      "healthy",
        "timestamp":   time.Now().UTC(),
        "version":     os.Getenv("APP_VERSION"),
        "environment": os.Getenv("ENVIRONMENT"),
    }

    // Check database connection
    if db != nil {
        if err := db.Ping(); err != nil {
            status["database"] = "unhealthy"
            status["status"] = "degraded"
            c.JSON(503, status)
            return
        }
        status["database"] = "healthy"
    }

    c.JSON(200, status)
}

Data Models & Schemas

// GitHub profile response model
type GitHubProfile struct {
    Username    string `json:"username" example:"mattmajestic"`
    Name        string `json:"name" example:"Matt"`
    Bio         string `json:"bio" example:"Full Stack Developer"`
    Followers   int    `json:"followers" example:"1250"`
    Following   int    `json:"following" example:"180"`
    PublicRepos int    `json:"public_repos" example:"45"`
    AvatarURL   string `json:"avatar_url" example:"https://github.com/avatar.jpg"`
    Location    string `json:"location" example:"San Francisco, CA"`
    Company     string `json:"company" example:"Majestic Coding"`
    Blog        string `json:"blog" example:"https://majesticcoding.com"`
}

// Twitch analytics response model
type TwitchAnalytics struct {
    ChannelName   string      `json:"channel_name" example:"majesticcoding"`
    Followers     int         `json:"followers" example:"8500"`
    TotalViews    int         `json:"total_views" example:"125000"`
    RecentStreams []Stream    `json:"recent_streams"`
    Metrics       Metrics     `json:"metrics"`
}

type Stream struct {
    Title       string    `json:"title" example:"Building Go APIs"`
    ViewerCount int       `json:"viewer_count" example:"145"`
    Duration    int       `json:"duration" example:"7200"` // seconds
    StartedAt   time.Time `json:"started_at"`
    GameName    string    `json:"game_name" example:"Software and Game Development"`
}

type Metrics struct {
    AvgViewers     float64 `json:"avg_viewers" example:"125.5"`
    PeakViewers    int     `json:"peak_viewers" example:"280"`
    StreamsThisMonth int   `json:"streams_this_month" example:"12"`
    HoursStreamed  float64 `json:"hours_streamed" example:"48.5"`
}

// Error response model
type ErrorResponse struct {
    Error     string `json:"error" example:"Not Found"`
    Message   string `json:"message" example:"The requested resource was not found"`
    Code      string `json:"code,omitempty" example:"RESOURCE_NOT_FOUND"`
    Timestamp string `json:"timestamp" example:"2024-01-15T10:30:00Z"`
}

// YouTube statistics model
type YouTubeStats struct {
    ChannelName   string `json:"channel_name" example:"Majestic Coding"`
    Subscribers   int    `json:"subscribers" example:"129000"`
    TotalViews    int64  `json:"total_views" example:"1500000"`
    VideoCount    int    `json:"video_count" example:"180"`
    RecentVideos  []Video `json:"recent_videos"`
}

type Video struct {
    Title       string `json:"title" example:"Go REST API Tutorial"`
    Views       int    `json:"views" example:"15000"`
    Likes       int    `json:"likes" example:"850"`
    Duration    string `json:"duration" example:"PT15M30S"`
    PublishedAt string `json:"published_at" example:"2024-01-10T14:30:00Z"`
}

Swagger Setup & Configuration

// main.go - Swagger initialization
package main

import (
    "github.com/gin-gonic/gin"
    "github.com/swaggo/gin-swagger"
    "github.com/swaggo/files"

    _ "majesticcoding.com/docs" // Generated swagger docs
)

// @title Majestic Coding API
// @version 1.0
// @description REST API for Majestic Coding platform
// @termsOfService https://majesticcoding.com/terms

// @contact.name Matt
// @contact.url https://majesticcoding.com
// @contact.email matt@majesticcoding.com

// @license.name MIT
// @license.url https://opensource.org/licenses/MIT

// @host majesticcoding.com
// @BasePath /api
// @schemes https http

func main() {
    router := gin.Default()

    // Swagger endpoint
    router.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))

    // API routes
    api := router.Group("/api")
    {
        api.GET("/github/:username", GetGitHubProfile)
        api.GET("/twitch/analytics", GetTwitchAnalytics)
        api.GET("/youtube/stats", GetYouTubeStats)
        api.GET("/metrics", GetMetrics)
        api.GET("/health", HealthCheck)
    }

    router.Run(":8080")
}

// Generate docs command
// Run this to update Swagger documentation:
// swag init

// Swagger generation configuration
// docs/docs.go (auto-generated)
// Package docs GENERATED BY SWAG; DO NOT EDIT
package docs

import "github.com/swaggo/swag"

const docTemplate = {
    "schemes": {{ marshal .Schemes }},
    "swagger": "2.0",
    "info": {
        "description": "{{escape .Description}}",
        "title": "{{.Title}}",
        "contact": {
            "name": "Matt",
            "url": "https://majesticcoding.com",
            "email": "matt@majesticcoding.com"
        },
        "license": {
            "name": "MIT",
            "url": "https://opensource.org/licenses/MIT"
        },
        "version": "{{.Version}}"
    },
    "host": "{{.Host}}",
    "basePath": "{{.BasePath}}",
    "paths": {}
}

func init() {
    swag.Register("swagger", &s{})
}

// Directory structure
/*
project/
├── main.go
├── docs/
│   ├── docs.go      (generated)
│   ├── swagger.json (generated)
│   └── swagger.yaml (generated)
├── api/
│   └── handlers/
│       ├── github.go
│       ├── twitch.go
│       └── youtube.go
└── models/
    ├── github.go
    ├── twitch.go
    └── response.go
*/

🚀 API Features

Interactive Testing: Test endpoints directly from Swagger UI
Auto-Generated: Documentation stays in sync with code changes
Type Safety: Go struct tags define JSON schema validation
Error Handling: Comprehensive HTTP status codes and error responses
Rate Limiting: Built-in protection against API abuse
Caching Headers: Optimize performance with appropriate cache policies