{"id":30110406,"url":"https://github.com/muratmirgun/socketeer","last_synced_at":"2025-08-10T04:45:19.933Z","repository":{"id":301784325,"uuid":"1009900263","full_name":"muratmirgun/socketeer","owner":"muratmirgun","description":"Modern, Swagger-Style WebSocket API Docs \u0026 Playground for Go","archived":false,"fork":false,"pushed_at":"2025-06-29T22:21:51.000Z","size":1119,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-08-07T18:03:48.772Z","etag":null,"topics":["docs","go","swagger","websocket"],"latest_commit_sha":null,"homepage":"","language":"HTML","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/muratmirgun.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-27T23:22:55.000Z","updated_at":"2025-07-03T08:28:13.000Z","dependencies_parsed_at":"2025-07-05T09:32:16.496Z","dependency_job_id":null,"html_url":"https://github.com/muratmirgun/socketeer","commit_stats":null,"previous_names":["muratmirgun/socketeer"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/muratmirgun/socketeer","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/muratmirgun%2Fsocketeer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/muratmirgun%2Fsocketeer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/muratmirgun%2Fsocketeer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/muratmirgun%2Fsocketeer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/muratmirgun","download_url":"https://codeload.github.com/muratmirgun/socketeer/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/muratmirgun%2Fsocketeer/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":269677511,"owners_count":24457858,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-10T02:00:08.965Z","response_time":71,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["docs","go","swagger","websocket"],"created_at":"2025-08-10T04:45:06.455Z","updated_at":"2025-08-10T04:45:19.881Z","avatar_url":"https://github.com/muratmirgun.png","language":"HTML","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://github.com/muratmirgun/socketeer/blob/main/internal/templates/logo.png\" alt=\"Socketeer Logo\" width=\"180\" /\u003e\n\u003c/p\u003e\n\n# Socketeer\n\n**Modern, Swagger-Style WebSocket API Docs \u0026 Playground for Go**\n\n[![Go Version](https://img.shields.io/badge/Go-1.21+-blue.svg)](https://golang.org)\n[![License](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)\n[![Go Report Card](https://goreportcard.com/badge/github.com/muratmirgun/socketeer)](https://goreportcard.com/report/github.com/muratmirgun/socketeer)\n[![Release](https://img.shields.io/github/v/release/muratmirgun/socketeer)](https://github.com/muratmirgun/socketeer/releases)\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://github.com/muratmirgun/socketeer/blob/main/banner.png\" alt=\"Socketeer UI Showcase\" width=\"100%\" /\u003e\n  \u003cbr/\u003e\n  \u003cem\u003eModern, interactive WebSocket API documentation and playground UI\u003c/em\u003e\n\u003c/p\u003e\n\nSocketeer is an open-source tool that generates interactive, Swagger-like documentation and playgrounds for your WebSocket APIs in Go.  \nIt parses special annotations in your Go code and produces a `wsapi.yaml` spec, which is visualized in a beautiful, build-free frontend.\n\n---\n\n## 📑 Table of Contents\n\n- [Features](#-features)\n- [Installation](#-installation)\n- [Quick Start](#-quick-start)\n- [CLI Commands](#-cli-commands)\n- [Annotation Reference](#-annotation-reference)\n- [Available Annotations](#️-available-annotations)\n- [Advanced Usage](#-advanced-usage)\n  - [Gin Middleware Integration](#gin-middleware-integration)\n- [Development](#-development)\n- [How It Works](#-how-it-works)\n- [Contributing](#-contributing)\n- [License](#-license)\n\n---\n\n## 🚀 Features\n\n- **Swagger-style API info annotations** (title, version, description, contact, license)\n- **Parse Go code for custom WebSocket annotations** (`@WebSocket`, `@Message`, `@Payload`, `@Group`, etc.)\n- **Struct-based payload support** (`@Payload MyStruct` or `@Payload dto.MyStruct`)\n- **Generate `wsapi.yaml` or JSON spec**\n- **Serve docs and playground via HTTP** (no build step required)\n- **Multi-client playground** (test with multiple virtual clients in one UI)\n- **Modern, responsive UI** (Swagger-inspired, with live playground)\n- **Cobra-powered CLI** (`init`, `generate`, `serve`, `version`)\n- **MIT licensed, easy to extend**\n\n---\n\n## 📦 Installation\n\n### From GitHub Releases\n\nDownload the latest release for your platform from [GitHub Releases](https://github.com/muratmirgun/socketeer/releases).\n\n### Using Go\n\n```sh\ngo install github.com/muratmirgun/socketeer@latest\n```\n\n---\n\n## 🏃‍♂️ Quick Start\n\n```sh\n# Install socketeer\ngo install github.com/muratmirgun/socketeer@latest\n\n# Navigate to your Go project\ncd your-go-project\n\n# Initialize socketeer project\nsocketeer init\n\n# Add annotations to your Go code (see below)\nsocketeer generate --src ./ --out ./wsdocs/wsapi.yaml\n\n# Serve the documentation\nsocketeer serve\n\n# Open http://localhost:8080 in your browser\n```\n\n---\n\n## 📋 CLI Commands\n\n### `socketeer init`\nInitialize a new socketeer project by creating a `wsdocs/` directory with base files.\n\n```sh\nsocketeer init\n```\n\n### `socketeer generate`\nGenerate `wsapi.yaml` spec from Go source annotations.\n\n```sh\n# Basic usage\nsocketeer generate\n\n# With custom source and output\nsocketeer generate --src ./internal --out ./docs/wsapi.yaml\n\n# Available flags:\n#   --src string   Source directory to scan for Go files (default \"./\")\n#   --out string   Output spec file (YAML) (default \"wsdocs/wsapi.yaml\")\n```\n\n### `socketeer serve`\nServe documentation and playground from a directory.\n\n```sh\n# Basic usage\nsocketeer serve\n\n# With custom directory and port\nsocketeer serve --dir ./docs\nSOCKETEER_PORT=3000 socketeer serve\n\n# Available flags:\n#   --dir string   Directory to serve static files from (default \"wsdocs\")\n# Environment variables:\n#   SOCKETEER_PORT  Port to serve on (default \"8080\")\n```\n\n### `socketeer version`\nShow socketeer version information.\n\n```sh\nsocketeer version\n```\n\n---\n\n## 📝 Annotation Reference\n\n### API Info Annotations\n\nAdd these annotations above your `main` function or at the top of your main Go file:\n\n```go\n// @title Socketeer WebSocket API Docs\n// @version 1.0.0\n// @description Real-time WebSocket API documentation with interactive playground\n// @contact.name Murat Mirgun\n// @contact.email murat@example.com\n// @license.name MIT\n// @license.url https://opensource.org/licenses/MIT\nfunc main() {\n    // ...\n}\n```\n\n### WebSocket Endpoint Annotations\n\n```go\n// @WebSocket CompanySocket\n// @Group Company Management\n// @URL ws://localhost:8080/ws/company\n// @Description Company management WebSocket channel for real-time operations\n// @Tags company, admin, real-time\n\n// @ConnectionParam name query string required User name for authentication\n// @ConnectionParam token header string required JWT token\n\n// @Message addCompany\n// @Send\n// @Description Add a new company to the system\n// @Payload dto.ReqAddCompany\n// @Tags company, create\n\n// @Message companyAdded\n// @Receive\n// @Description Company added successfully\n// @Payload dto.ResAddCompany\n// @Tags company, response\n\n// @Message updateCompany\n// @Send\n// @Description Update an existing company\n// @Payload dto.ReqUpdateCompany\n// @Tags company, update\n\n// @Message companyUpdated\n// @Receive\n// @Description Company updated successfully\n// @Payload dto.ResUpdateCompany\n// @Tags company, response\n\n// @Message deleteCompany\n// @Send\n// @Description Delete a company\n// @Payload {\"id\": \"string\"}\n// @Tags company, delete\n\n// @Message companyDeleted\n// @Receive\n// @Description Company deleted successfully\n// @Payload {\"id\": \"string\", \"success\": true}\n// @Tags company, response\n\n// @Message companyError\n// @Receive\n// @Description Error response for company operations\n// @Payload {\"error\": \"string\", \"code\": \"string\"}\n// @Error 400 Bad Request\n// @Error 404 Company not found\n// @Error 500 Internal Server Error\n// @Tags company, error\n\nfunc CompanySocketHandler(c *gin.Context) {\n    // WebSocket handler implementation\n}\n```\n\n### Struct-based Payload Example\n\n```go\npackage dto\n\n// ReqAddCompany represents a company creation request\ntype ReqAddCompany struct {\n    // Name of the company\n    Name string `json:\"name\" validate:\"required,min=2,max=100,alpha_space\" Example:\"Acme Inc\"`\n    // Status of the company (1: active, 0: inactive)\n    Status int64 `json:\"status\" validate:\"required\" Example:1`\n    // Company description\n    Description string `json:\"description\" Example:\"Leading technology company\"`\n    // Founded year\n    FoundedYear int `json:\"founded_year\" Example:2020`\n}\n\n// ResAddCompany represents a company creation response\ntype ResAddCompany struct {\n    // Company ID\n    ID string `json:\"id\" Example:\"comp_123456\"`\n    // Company name\n    Name string `json:\"name\" Example:\"Acme Inc\"`\n    // Creation timestamp\n    CreatedAt string `json:\"created_at\" Example:\"2024-01-15T10:30:00Z\"`\n    // Success status\n    Success bool `json:\"success\" Example:true`\n}\n```\n\n---\n\n## 🏷️ Available Annotations\n\n### API Info Annotations\n| Annotation | Description | Example |\n|------------|-------------|---------|\n| `@title` | API title | `@title My WebSocket API` |\n| `@version` | API version | `@version 1.0.0` |\n| `@description` | API description | `@description Real-time API for chat` |\n| `@contact.name` | Contact name | `@contact.name John Doe` |\n| `@contact.email` | Contact email | `@contact.email john@example.com` |\n| `@license.name` | License name | `@license.name MIT` |\n| `@license.url` | License URL | `@license.url https://opensource.org/licenses/MIT` |\n\n### WebSocket Annotations\n| Annotation | Description | Example |\n|------------|-------------|---------|\n| `@WebSocket` | WebSocket name | `@WebSocket ChatSocket` |\n| `@Group` | Group name | `@Group Chat Management` |\n| `@URL` | WebSocket URL | `@URL ws://localhost:8080/ws/chat` |\n| `@Description` | WebSocket description | `@Description Real-time chat functionality` |\n| `@Tags` | Tags for categorization | `@Tags chat, real-time, messaging` |\n| `@ConnectionParam` | Connection parameters | `@ConnectionParam token header string required JWT token` |\n\n### Message Annotations\n| Annotation | Description | Example |\n|------------|-------------|---------|\n| `@Message` | Message type/name | `@Message sendMessage` |\n| `@Send` | Send direction | `@Send` |\n| `@Receive` | Receive direction | `@Receive` |\n| `@Payload` | Message payload | `@Payload dto.ChatMessage` |\n| `@Error` | Error response | `@Error 400 Bad Request` |\n| `@Deprecated` | Mark as deprecated | `@Deprecated` |\n\n### Struct Field Annotations\n| Annotation | Description | Example |\n|------------|-------------|---------|\n| `Example:` | Field example value | `// Example: \"Hello World\"` |\n\n---\n\n## 🔧 Advanced Usage\n\n### Custom Port Configuration\n\n```sh\n# Set custom port via environment variable\nexport SOCKETEER_PORT=3000\nsocketeer serve\n\n# Or inline\nSOCKETEER_PORT=3000 socketeer serve\n```\n\n### Multiple WebSocket Endpoints\n\n```go\n// Chat WebSocket\n// @WebSocket ChatSocket\n// @Group Chat\n// @URL ws://localhost:8080/ws/chat\n// @Description Real-time chat functionality\n// @Tags chat, messaging\n\n// @Message sendMessage\n// @Send\n// @Description Send a chat message\n// @Payload dto.ChatMessage\n\n// @Message messageReceived\n// @Receive\n// @Description Message received from another user\n// @Payload dto.ChatMessage\n\nfunc ChatSocketHandler(c *gin.Context) {\n    // Chat handler\n}\n\n// Notification WebSocket\n// @WebSocket NotificationSocket\n// @Group Notifications\n// @URL ws://localhost:8080/ws/notifications\n// @Description Real-time notifications\n// @Tags notifications, alerts\n\n// @Message subscribe\n// @Send\n// @Description Subscribe to notifications\n// @Payload {\"user_id\": \"string\"}\n\n// @Message notification\n// @Receive\n// @Description Receive notification\n// @Payload dto.Notification\n\nfunc NotificationSocketHandler(c *gin.Context) {\n    // Notification handler\n}\n```\n\n### Error Handling\n\n```go\n// @Message userAction\n// @Send\n// @Description Perform user action\n// @Payload dto.UserAction\n\n// @Message actionResult\n// @Receive\n// @Description Action result\n// @Payload dto.ActionResult\n\n// @Message actionError\n// @Receive\n// @Description Action error\n// @Payload {\"error\": \"string\", \"code\": \"string\"}\n// @Error 400 Invalid input\n// @Error 401 Unauthorized\n// @Error 403 Forbidden\n// @Error 404 Not found\n// @Error 500 Internal server error\n```\n\n### Gin Middleware Integration\n\nYou can serve Socketeer documentation and playground directly from your Gin application using the built-in middleware:\n\n```go\nimport (\n    \"github.com/gin-gonic/gin\"\n    \"github.com/muratmirgun/socketeer/pkg/socketeer\"\n)\n\nfunc main() {\n    r := gin.Default()\n\n    // Serve Socketeer docs at /docs (default: wsdocs directory)\n    r.Use(socketeer.GinMiddleware(\u0026socketeer.Config{\n        Path:       \"/docs\",              // URL path to serve docs\n        StaticPath: \"wsdocs\",             // Directory for static files (index.html, logo.png, etc.)\n        SpecPath:   \"wsdocs/wsapi.yaml\",  // Path to wsapi.yaml\n        EnableCORS: true,                  // Enable CORS headers (optional)\n    }))\n\n    // Your WebSocket and API routes here\n    r.GET(\"/ws/company\", CompanySocketHandler)\n\n    r.Run(\":8080\")\n}\n```\n\n- Artık http://localhost:8080/docs adresinden Socketeer arayüzüne erişebilirsiniz.\n- `socketeer.GinMiddleware(nil)` ile varsayılan ayarları da kullanabilirsiniz.\n\n---\n\n## 🛠️ Development\n\n### Building from Source\n\n```sh\ngit clone https://github.com/muratmirgun/socketeer.git\ncd socketeer\ngo build -o socketeer .\n```\n\n### Running Tests\n\n```sh\ngo test -v ./...\n```\n\n### Linting\n\n```sh\ngolangci-lint run\n```\n\n---\n\n## 📖 How It Works\n\n1. **Annotate** your Go code with Swagger-style and WebSocket-specific comments\n2. **Generate** the spec: `socketeer generate --src ./ --out ./wsdocs/wsapi.yaml`\n3. **Serve** the docs and playground: `socketeer serve`\n4. **Explore and test** your WebSocket API in the browser with a modern, interactive UI\n\n---\n\n## 🤝 Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n---\n\n## 📄 License\n\nMIT License - see the [LICENSE](LICENSE) file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmuratmirgun%2Fsocketeer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmuratmirgun%2Fsocketeer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmuratmirgun%2Fsocketeer/lists"}