How to Unify Swagger2.0 Docs with GF2 Routing: A Practical Guide

Background

In a previous frontend project we adopted Swagger 2.0 syntax rules and defined a custom response data structure, but the documentation and parameter mapping were kept separate, leading to two major issues.

Problems with the Current Approach

Parameters such as game_id that are required and need validation are missing from the generated documentation.

Even when documented, the actual code may not receive the parameter, creating ambiguity for maintenance and early integration.

Lack of Consistent Parameter Handling

Parameter reception, validation, and transmission are performed via independent keys, and each project or developer may implement them differently, causing inconsistency.

Unified Parameter Definition Strategy

We already have a set of GF (Go Frame) parameter assignment and validation rules. The goal is to keep these rules while making them compatible with the existing route injection mechanism. After defining parameters, documentation generation, parsing, validation, and assignment all rely on that definition, and the controller receives request data that matches the defined structure.

Routing Scheme

Original Routing Scheme

The old scheme consists of two core steps:

Route injection: Convert a struct and method name into a key used for route lookup, binding the key to the executing method for later retrieval.

Route retrieval: Split the incoming path, map the two segments to a struct name and method name, and locate the corresponding method.

Adjusted Scheme

We introduce an outer adapter layer that provides two functions:

Compatibility: Wrap the original

func (c *cXXX) XXX(ctx context.Context, req XxxReq) (XxxRes, error)

signature into the GF‑style

func (a *XXX) XXX(base *api_server_base.Base, arguments ...interface{}) error

while preserving the routing logic.

Documentation generation: Pre‑generate a goai.AddInput struct so that the GF framework can read it and produce the OpenAPI JSON automatically.

Implementation Details

The GF framework converts bound structs into OpenAPI JSON when the /api.json endpoint is requested. The process is:

Router finds the openapiSpec method and serialises the openapi variable to JSON.

The framework inspects the injected function; if it matches the

func (c *cXXX) XXX(ctx context.Context, req XxxReq) (XxxRes, error)

pattern, it extracts the request and response structs, reads their g.Meta tags for path and method, and fills the OpenAPI definition.

Key code snippets (illustrated in the images) show how baseFunc wraps the original handler, how AddInput is constructed, and how the OpenAPI fields path, method, and object are populated.

Result and Demonstration

After applying the adapter, the GF2 routing aligns with the legacy base routing, and any project can achieve the same effect by modifying only the route injection logic. The following screenshots illustrate the controller logic, parameter handling, local service startup, and the final generated OpenAPI documentation.

With these changes, the GF2 routing and the legacy base routing are fully unified, and other projects can achieve the same result by simply adapting the route injection method.