{"id":29418419,"url":"https://github.com/vuongtlt13/auto-fiber","last_synced_at":"2025-07-11T23:04:54.127Z","repository":{"id":301114442,"uuid":"1008131948","full_name":"vuongtlt13/auto-fiber","owner":"vuongtlt13","description":"A FastAPI-like wrapper for the Fiber web framework in Go, providing automatic request parsing, validation, and OpenAPI/Swagger documentation generation.","archived":false,"fork":false,"pushed_at":"2025-07-04T04:27:32.000Z","size":6199,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-07-04T04:33:38.404Z","etag":null,"topics":["fiber","fiber-go","go","golang","web"],"latest_commit_sha":null,"homepage":"","language":"Go","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/vuongtlt13.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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-25T04:46:02.000Z","updated_at":"2025-07-04T04:27:28.000Z","dependencies_parsed_at":"2025-06-25T08:33:29.804Z","dependency_job_id":"9b28f45f-5c3f-4790-9dc1-fb4580cec30f","html_url":"https://github.com/vuongtlt13/auto-fiber","commit_stats":null,"previous_names":["vuongtlt13/auto-fiber"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/vuongtlt13/auto-fiber","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vuongtlt13%2Fauto-fiber","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vuongtlt13%2Fauto-fiber/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vuongtlt13%2Fauto-fiber/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vuongtlt13%2Fauto-fiber/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vuongtlt13","download_url":"https://codeload.github.com/vuongtlt13/auto-fiber/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vuongtlt13%2Fauto-fiber/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":264910722,"owners_count":23682124,"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","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":["fiber","fiber-go","go","golang","web"],"created_at":"2025-07-11T23:04:53.104Z","updated_at":"2025-07-11T23:04:54.116Z","avatar_url":"https://github.com/vuongtlt13.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# AutoFiber\n\nA FastAPI-like wrapper for the Fiber web framework in Go, providing automatic request parsing, validation, and OpenAPI/Swagger documentation generation.\n\n## Features\n\n- **🔄 Complete Request/Response Flow**: Parse request → Validate request → Execute handler → Validate response → Return JSON\n- **🧠 Smart Parsing**: Auto-detect the best source based on HTTP method (GET: path→query, POST: body→path→query)\n- **🏷️ Unified Parse Tag**: Single `parse` tag with options like `required` and `default`\n- **🗺️ Map/Interface Parsing**: Parse structs from maps, interfaces, and other data structures\n- **✅ Request Validation**: Built-in validation using struct tags with `go-playground/validator`\n- **✅ Response Validation**: Validate response data before sending to client\n- **📚 Auto Documentation**: Generate OpenAPI 3.0 specification and Swagger UI\n- **🔒 Type Safety**: Full type safety with Go generics\n- **⚙️ Route Options**: Flexible route configuration with options pattern\n- **🔌 Middleware Integration**: Seamless integration with Fiber middleware\n- **🎯 Clean Architecture**: Modular design with separate concerns\n- **OpenAPI Schema Naming \u0026 Generic Response**:\n  - **Schema Naming:** AutoFiber generates OpenAPI schema names that are RFC3986-compliant. For generic structs, the schema name will be in the form `APIResponse_User` (for `APIResponse[User]`). For non-generic structs, the schema name is simply the type name (e.g., `LoginResponse`).\n  - **Generic Response Support:** You can use generic response wrappers for consistent API responses. Example:\n    ```go\n    type APIResponse[T any] struct {\n        Code    int    `json:\"code\"`\n        Message string `json:\"message\"`\n        Data    T      `json:\"data\"`\n    }\n    // Usage in route:\n    app.Get(\"/user\", handler.GetUser, autofiber.WithResponseSchema(APIResponse[User]{}))\n    ```\n  - **Request Body Rules:** Only POST, PUT, and PATCH methods generate a `requestBody` in the OpenAPI spec. GET, DELETE, HEAD, and OPTIONS never have a request body, even if a request schema is provided.\n\n## Installation\n\n```sh\ngo get github.com/vuongtlt13/auto-fiber\n```\n\n## Project Structure\n\n```\nauto-fiber/\n  app.go            // App core: AutoFiber struct, route registration, group, listen, etc.\n  group.go          // Route grouping logic\n  handlers.go       // Handler creation, signature validation, error handling\n  parser.go         // Request parsing from multiple sources (body, query, path, ...)\n  validator.go      // Response validation logic\n  map_parser.go     // Parse struct from map/interface\n  docs.go           // OpenAPI/Swagger documentation generation\n  options.go        // Route option functions (WithRequestSchema, WithResponseSchema, ...)\n  types.go          // Core types, RouteOptions, ParseSource, etc.\n  example/          // Example usage and demo app\n  docs/             // Documentation and guides\n```\n\n- **app.go**: Initialize app, register routes, groups, listen.\n- **group.go**: Support for route groups, group middleware.\n- **handlers.go**: Create handlers with correct signature, signature validation.\n- **parser.go**: Automatically parse requests from multiple sources (body, query, path, header, cookie).\n- **validator.go**: Validate response before returning to client.\n- **map_parser.go**: Support parsing struct from map/interface (for test, mock, ...).\n- **docs.go**: Generate OpenAPI spec, serve Swagger UI/docs.\n- **options.go**: Option functions for routes (schema, tags, description, ...).\n- **types.go**: Define core types, RouteOptions, ParseSource, ...\n\n## Quick Start\n\n```go\npackage main\n\nimport (\n    \"time\"\n    \"github.com/gofiber/fiber/v2\"\n    autofiber \"github.com/vuongtlt13/auto-fiber\"\n)\n\n// Request schema with parse tag\n// (parse from path, query, header, body)\ntype CreateUserRequest struct {\n    OrgID    int    `parse:\"path:org_id\" validate:\"required\"`\n    Role     string `parse:\"query:role\" validate:\"required,oneof=admin user\"`\n    Email    string `json:\"email\" validate:\"required,email\"`\n    Password string `json:\"password\" validate:\"required,min=8\"`\n    Name     string `json:\"name\" validate:\"required\"`\n}\n\ntype UserResponse struct {\n    ID        int       `json:\"id\" validate:\"required\"`\n    Email     string    `json:\"email\" validate:\"required,email\"`\n    Name      string    `json:\"name\" validate:\"required\"`\n    Role      string    `json:\"role\" validate:\"required,oneof=admin user\"`\n    CreatedAt time.Time `json:\"created_at\" validate:\"required\"`\n}\n\ntype APIResponse[T any] struct {\n    Code    int    `json:\"code\"`\n    Message string `json:\"message\"`\n    Data    T      `json:\"data\"`\n}\n\ntype UserHandler struct{}\n\n// Handler signature for AutoFiber:\nfunc (h *UserHandler) CreateUser(c *fiber.Ctx, req *CreateUserRequest) (interface{}, error) {\n    user := UserResponse{\n        ID:        1,\n        Email:     req.Email,\n        Name:      req.Name,\n        Role:      req.Role,\n        CreatedAt: time.Now(),\n    }\n    return user, nil\n}\n\n// Handler returning generic response\nfunc (h *UserHandler) GetUser(c *fiber.Ctx) (interface{}, error) {\n    user := UserResponse{\n        ID:        1,\n        Email:     \"user@example.com\",\n        Name:      \"John Doe\",\n        Role:      \"user\",\n        CreatedAt: time.Now(),\n    }\n    return APIResponse[UserResponse]{Code: 0, Message: \"success\", Data: user}, nil\n}\n\nfunc main() {\n    app := autofiber.NewWithOptions(\n        fiber.Config{EnablePrintRoutes: true},\n        autofiber.WithOpenAPI(autofiber.OpenAPIInfo{\n            Title:       \"AutoFiber API\",\n            Description: \"A sample API with complete request/response flow\",\n            Version:     \"0.3.1\",\n        }),\n    )\n\n    handler := \u0026UserHandler{}\n\n    app.Post(\"/organizations/:org_id/users\", handler.CreateUser,\n        autofiber.WithRequestSchema(CreateUserRequest{}),\n        autofiber.WithResponseSchema(UserResponse{}),\n        autofiber.WithDescription(\"Create a new user in an organization\"),\n        autofiber.WithTags(\"users\", \"admin\"),\n    )\n\n    app.Get(\"/user\", handler.GetUser,\n        autofiber.WithResponseSchema(APIResponse[UserResponse]{}),\n        autofiber.WithDescription(\"Get a user with generic response\"),\n        autofiber.WithTags(\"users\"),\n    )\n\n    app.ServeDocs(\"/docs\")\n    app.ServeSwaggerUI(\"/swagger\", \"/docs\")\n    app.Listen(\":3000\")\n}\n```\n\n## Complete Request/Response Flow\n\nAutoFiber provides a complete flow similar to FastAPI:\n\n```\nParse Request → Validate Request → Execute Handler → Validate Response → Return JSON\n```\n\n### Flow Details\n\n1. **Parse Request**: Automatically parse from multiple sources (body, query, path, headers, cookies)\n2. **Validate Request**: Validate parsed data against struct tags\n3. **Execute Handler**: Run your business logic\n4. **Validate Response**: Validate response data before sending\n5. **Return JSON**: Send validated response to client\n\n## Handler Signatures\n\n**Required Signatures for AutoFiber:**\n\n```go\n// Standard handler with request parsing: return data and error\nfunc (h *Handler) CompleteHandler(c *fiber.Ctx, req *RequestSchema) (interface{}, error) {\n    return ResponseSchema{...}, nil\n}\n\n// Handler without request parsing: return data and error\nfunc (h *Handler) SimpleHandler(c *fiber.Ctx) (interface{}, error) {\n    return ResponseSchema{...}, nil\n}\n```\n\n**Use only for health check or custom response:**\n\n```go\nfunc (h *Handler) Health(c *fiber.Ctx) error {\n    return c.JSON(fiber.Map{\"status\": \"ok\"})\n}\n```\n\n**NOT supported (will cause panic):**\n\n```go\n// Do not use this signature - AutoFiber requires (interface{}, error) return\nfunc (h *Handler) BadHandler(c *fiber.Ctx, req *RequestSchema) error {\n    return c.JSON(...)\n}\n```\n\n\u003e **Note:** AutoFiber requires handlers to return `(interface{}, error)` for automatic JSON marshaling and response validation. The old signature `func(c *fiber.Ctx, req *T) error` is no longer supported.\n\n## Documentation\n\n- [docs/README.md](docs/README.md) - Documentation index \u0026 guides\n- [docs/structs-and-tags.md](docs/structs-and-tags.md) - Struct/tag/validation best practices\n- [docs/complete-flow.md](docs/complete-flow.md) - Full request/response flow\n- [docs/validation-rules.md](docs/validation-rules.md) - Validation rules \u0026 custom validators\n- [docs/migration-guide.md](docs/migration-guide.md) - Migrate from old handler signatures\n- [example/](example/) - Example app\n\n## Contributing\n\nIf you find any issues or want to improve the documentation:\n\n1. Check the existing documentation first\n2. Create an issue or pull request\n3. Follow the same format and style as existing docs\n4. Include practical examples and use cases\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvuongtlt13%2Fauto-fiber","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvuongtlt13%2Fauto-fiber","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvuongtlt13%2Fauto-fiber/lists"}