📝 [Proposal]: Goge 🍅 — Adding "API Schemas" Support in Fiber Framework (V3) via Annotated Go Functions

[xehrad]

Hello Fiber community!

I’m excited to share Goge, a new library I wrote to help with exactly what many of you have requested in issue #3271: first-class support for API schemas, validation, documentation, and less boilerplate. Goge generates API handlers and OpenAPI specs from annotated Go functions.

Below is a write-up of what Goge is, why it might help, how it works, and how it could integrate (or merge) with Fiber moving forward.

What is Goge 🍅

• Goge (“Go + Generate”) is a code generator for the Fiber framework.

• It uses Go annotations on your handler functions (comments + struct tags) to automatically generate:

  1. Fiber request handlers (that parse params, queries, headers, request body)
  2. Router registrations (method + path)
  3. OpenAPI (OpenAPI 3) specification (with details about path params, query parameters, headers, request & response schemas)

Why Goge Helps

Goge addresses many of the problems raised in the Fiber “API Schemas” proposal:

• Less boilerplate: Parsing params, queries, headers, and body is auto-generated.
• Consistency: Single source of truth (struct tags + annotations).
• Docs always in sync: OpenAPI spec generated automatically.
• Type safety: Compile-time checked via Go structs.

Current Status

• Repo: https://github.com/xehrad/goge
• MIT licensed, Go 1.24+
• Supports path params, queries, headers, JSON body parsing
• Generates OpenAPI JSON alongside handler code

Possible Next Steps

• Validation rules (min, max, regex, required, etc.)
• Client SDKs from generated OpenAPI spec
• Versioning support for evolving APIs
• Integration with Fiber CLI / tooling

Respectful Suggestion for Fiber v3

Since this feature aligns closely with the ongoing discussions around API schemas and better validation in Fiber, I would like to respectfully propose that Goge (or its core ideas) become part of Fiber v3.

I believe integrating schema-driven handlers and auto-documentation at the framework level would bring huge value to developers, while still keeping Fiber’s philosophy of being lightweight and developer-friendly.

Example

The proposal (via Goge) aligns closely with the design philosophy of Express.js, where route definitions and handler parameters are concise and intuitive. Express encourages using request/response objects directly, while Fiber + Goge brings a typed, Go-idiomatic layer on top of that.

type PingParams struct {
    ID    string `gogeUrl:"id"`              // read from the URL path
    Auth  string `gogeHeader:"Authorization"`// read from HTTP header
    Query string `gogeQuery:"filter"`        // read from the query String
    Page  int    `gogeQuery:"page"`          // read from the query Int
    Name  string `json:"name"`               // from POST/PATCH/PUT body
}

//goge:api method=POST path=/ping/:id
func Ping(c *fiber.Ctx, params *PingParams) (*PingResp, error) {
    return &PingResp{ID: params.ID}, nil
}

After go generate, Goge produces both the handler code (with request parsing) and the OpenAPI spec JSON.

// Code generated by goge; DO NOT EDIT.

func PingHandler(c *fiber.Ctx) error {
  req := new(PingParams)
  c.BodyParser(req)

  req.ID = c.Params("id")
  req.Auth = c.Get("Authorization")
  req.Query = c.Query("filter")
  req.Page = c.QueryInt("page")

  res, _ := Ping(c, req)
  return c.JSON(res)
}


func GogeRouter(app *fiber.App) {
    app.Add("GET",  "/swagger", SwaggerUIHandler) // Swagger endpoints
    app.Add("POST", "/ping/:id", PingHandler)     // API endpoints
}

This mirrors the simplicity of Express.js routing but provides the added benefits of type safety, automatic parsing, and OpenAPI generation. Developers transitioning from Express will recognize the structure immediately while enjoying Go’s static typing.

HTTP RFC Standards Compliance

The feature is designed to comply with HTTP/1.1 and HTTP/2 RFCs:

• Path parameters, queries, and headers are parsed and mapped without modification, preserving case-insensitivity for headers and correct percent-decoding for queries (RFC 3986, RFC 7230).
• Request body parsing leverages existing Fiber/Go JSON handling, which follows standard Content-Type negotiation rules.
• Error responses for validation failures (planned extension) will return appropriate HTTP status codes (e.g., 400 Bad Request, 422 Unprocessable Entity), in line with RFC semantics.

In short, the proposal is compliant with HTTP RFCs and builds on Fiber’s already standards-aligned core.

API Stability

Stability is a core design goal. The approach relies on:

1. Go struct tags + annotations — a well-established and stable mechanism in Go, unlikely to change in the language itself.
2. Code generation — the generated handlers are plain Fiber code, meaning the runtime API surface is stable and not dependent on reflection or hidden magic.
3. OpenAPI as a contract — since Goge emits OpenAPI specs, the API behavior is locked in schema form, minimizing surprises.
4. Backward compatibility strategy — new features (validation rules, SDK generation, etc.) will be added in a backward-compatible way, while the base handler generation and tag syntax will remain unchanged.

This ensures developers can adopt the feature in Fiber v3 without fear of deprecations or breaking changes in the near future. The schema definitions themselves become the single source of truth, reinforcing long-term stability.

Feedback

I’d love the community’s feedback on:

• What syntax feels most natural?
• Which validation features are essential?
• Should this live as a standalone library, or be merged into Fiber itself?

Thanks for reading, and I look forward to your thoughts!

Checklist:

• I agree to follow Fiber's Code of Conduct.
• I have searched for existing issues that describe my proposal before opening this one.
• I understand that a proposal that does not meet these guidelines may be closed without explanation.

[gaby]

@xehrad This doesn't belong here, just add a comment in the other openapi related issues.

PR #3702 will add support for auto generating the spec.

Feel free to submit a PR in https://github.com/gofiber/awesome-fiber so we can list your library there.

[xehrad]

Thank you for the feedback. 🙏
I just want to clarify that my proposal is not only about generating OpenAPI specs.

The main point of Goge is to provide a schema-driven way to build routing in Fiber v3, where request parsing (params, queries, headers, body) and handler wiring are auto-generated from annotated Go code.

OpenAPI output is just a by-product. The real feature is to bring type-safe routing definitions into Fiber itself, reducing boilerplate and making APIs more consistent.

That’s why my respectful request is for this idea to be considered as a core feature in Fiber v3, not only listed under OpenAPI-related libraries.

If the team agrees, I’d be happy to work on a proof-of-concept PR to show how this can be integrated into v3 routing.

@gaby please reopen this issue

[gaby]

@xehrad We are too late to make such a big change for v3. The industry standard is to use OpenAPI, if Goge gets adopted by the Golang community we can consider adding it in the future.