HTTP Route Annotations Reference

This document provides a comprehensive reference for all available annotations used in GoFrame’s HTTP route generation system. These annotations are used by the router generator, URL helper generator, and TypeScript client generator.

Basic Syntax

Route annotations are defined using special comments above your handler methods:


// goframe:http_route parameter=value parameter2=value2
func (h *Handler) Method() http.HandlerFunc {
    // Implementation
}

Core Parameters

`path` (Required)

Defines the URL path for the route.


// goframe:http_route path=/users
// goframe:http_route path=/users/{id}
// goframe:http_route path=/api/v1/users/{id}/posts

Syntax:

Static paths: /users, /api/v1/health
Path parameters: /users/{id}, /posts/{slug}
Nested paths: /users/{user_id}/posts/{post_id}

`method`

Specifies the HTTP method(s) for the route. Defaults to GET if omitted.


// Single method
// goframe:http_route path=/users method=POST
// goframe:http_route path=/users method=GET
// goframe:http_route path=/users method=PUT
// goframe:http_route path=/users method=DELETE
// goframe:http_route path=/users method=PATCH
 
// Multiple methods
// goframe:http_route path=/users method=[GET,POST]
// goframe:http_route path=/items method=[GET,POST,PUT]

Supported Methods: GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS

Request/Response Type Parameters

`request`

Specifies the request type for the route. If omitted, the generator looks for a type named {MethodName}Request.


// Explicit request type
// goframe:http_route path=/users method=POST request=CreateUserRequest
 
// Auto-detected (looks for CreateUserRequest)
// goframe:http_route path=/users method=POST
func (h *Handler) CreateUser() http.HandlerFunc { ... }

`response`

Specifies the response type for the route. If omitted, the generator looks for a type named {MethodName}Response.


// Simple response
// goframe:http_route path=/users method=GET response=UserListResponse
 
// Auto-detected (looks for GetUsersResponse)
// goframe:http_route path=/users method=GET
func (h *Handler) GetUsers() http.HandlerFunc { ... }

Advanced Response Handling

Status-Specific Responses

Define different response types for different HTTP status codes:


// Single status code
// goframe:http_route path=/login method=POST response=200:LoginSuccessResponse
 
// Multiple status codes
// goframe:http_route path=/login method=POST response=200:LoginSuccessResponse response=401:LoginErrorResponse response=400:ValidationErrorResponse

Status Code Patterns

Use patterns to match ranges of status codes:


// Wildcard patterns
// goframe:http_route path=/process method=POST response=2xx:SuccessResponse response=4xx:ClientErrorResponse response=5xx:ServerErrorResponse
 
// Specific ranges
// goframe:http_route path=/upload method=POST response=200-201:UploadSuccessResponse response=400-499:ClientErrorResponse

Special Response Types

GoFrame provides special response type keywords:


// Error responses (automatically maps to 4xx/5xx)
// goframe:http_route path=/login method=POST response=200:LoginResponse response=401:Error
 
// Redirect responses (automatically maps to 3xx)
// goframe:http_route path=/redirect method=GET response=302:Redirect
 
// Explicit error/redirect in status declarations
// goframe:http_route path=/auth method=POST response=200:AuthResponse response=401:TYPE_ERROR response=302:TYPE_REDIRECT

Special Keywords:

Error - Maps to 4xx/5xx status codes
Redirect - Maps to 3xx status codes
TYPE_ERROR - Explicit error response
TYPE_REDIRECT - Explicit redirect response

Route Naming

`name`

Provides a custom name for the route, used in URL helpers and TypeScript client generation:


// Custom route name
// goframe:http_route path=/users method=GET name=ListAllUsers
func (h *Handler) GetUsers() http.HandlerFunc { ... }
 
// Results in URL helper: urls.User().ListAllUsers()
// Results in TS client: UserClient.listAllUsers()

Named Routes for Different Paths/Methods

Assign different names for the same handler method with different paths or methods:


// goframe:http_route path=/users method=GET name=ListUsers
// goframe:http_route path=/admin/users method=GET name=AdminListUsers  
func (h *Handler) GetUsers() http.HandlerFunc { ... }

Headers and Security

`required_header`

Specifies headers that must be present in the request:


// Single required header
// goframe:http_route path=/protected method=GET required_header=Authorization
 
// Multiple required headers
// goframe:http_route path=/api/data method=POST required_header=Authorization required_header=Content-Type

Complete Examples

Basic CRUD Operations


type UserHandler struct {}
 
type CreateUserRequest struct {
    Name  string `json:"name"`
    Email string `json:"email"`
}
 
type CreateUserResponse struct {
    ID   int    `json:"id"`
    Name string `json:"name"`
}
 
type GetUserRequest struct {
    ID string `path:"id"`
}
 
type GetUserResponse struct {
    ID    int    `json:"id"`
    Name  string `json:"name"`
    Email string `json:"email"`
}
 
// goframe:http_route path=/users method=GET
func (h *UserHandler) GetUsers() http.HandlerFunc { ... }
 
// goframe:http_route path=/users method=POST
func (h *UserHandler) CreateUser() http.HandlerFunc { ... }
 
// goframe:http_route path=/users/{id} method=GET
func (h *UserHandler) GetUser() http.HandlerFunc { ... }
 
// goframe:http_route path=/users/{id} method=PUT
func (h *UserHandler) UpdateUser() http.HandlerFunc { ... }
 
// goframe:http_route path=/users/{id} method=DELETE
func (h *UserHandler) DeleteUser() http.HandlerFunc { ... }

Advanced Authentication Endpoint


type AuthRequest struct {
    Username string `json:"username"`
    Password string `json:"password"`
}
 
type AuthSuccessResponse struct {
    Token string `json:"token"`
    User  User   `json:"user"`
}
 
type AuthErrorResponse struct {
    Message string `json:"message"`
    Code    string `json:"code"`
}
 
// goframe:http_route path=/auth/login method=POST request=AuthRequest response=200:AuthSuccessResponse response=401:AuthErrorResponse response=400:AuthErrorResponse name=UserLogin
func (h *AuthHandler) Login() http.HandlerFunc { ... }

File Upload with Multiple Response Types


type UploadRequest struct {
    UserID int                   `path:"user_id"`
    File   *multipart.FileHeader `file:"avatar"`
    Alt    string               `form:"alt_text"`
}
 
type UploadSuccessResponse struct {
    URL      string `json:"url"`
    FileSize int64  `json:"file_size"`
}
 
// goframe:http_route path=/users/{user_id}/avatar method=POST required_header=Authorization response=201:UploadSuccessResponse response=4xx:Error response=413:Error
func (h *UserHandler) UploadAvatar() http.HandlerFunc { ... }

Multi-Method Route


// goframe:http_route path=/items method=[GET,POST] response=200:ItemListResponse response=201:ItemCreatedResponse response=4xx:Error
func (h *ItemHandler) ManageItems() http.HandlerFunc {
    return httpx.Wrap(func(r *http.Request) (httpx.Response, error) {
        switch r.Method {
        case "GET":
            // Return list of items
        case "POST":
            // Create new item
        }
    })
}

Generator Usage

These annotations are automatically processed by GoFrame generators:

Router Generator


# Generates router.go files with route registrations
bin/goframe g router

URL Helper Generator


# Generates type-safe URL building functions
bin/goframe g url-helper

TypeScript Client Generator


# Generates TypeScript client with Zod validation
bin/goframe g client --file ./web/api.ts

Best Practices

Consistent Naming: Use consistent naming patterns for request/response types
Explicit Types: Specify request/response types for complex routes
Status Codes: Use appropriate status code patterns for different response scenarios
Path Parameters: Use descriptive parameter names in path definitions
Method Selection: Choose appropriate HTTP methods for each operation
Security: Always specify required headers for protected endpoints
Documentation: Use descriptive route names for better generated code readability

Validation Rules

path parameter is required for all routes
Method names must be valid HTTP methods
Status codes must be valid HTTP status codes (100-599)
Request/response types must be valid Go type names
Path parameters must be enclosed in curly braces: {param}
Multiple methods must be enclosed in square brackets: [GET,POST]