api-generation

name	api-generation
description	Generate TypeScript API client from Swagger/Go comments. Use when updating API endpoints, adding new routes, or regenerating the frontend API client after backend changes.
allowed-tools	Read, Edit, Write, Bash, Glob, Grep

API Generation

Generate typed TypeScript API client from Go Swagger comments using swag + Orval.

Workflow

Go Handler → swag init → swagger.json → Orval → TypeScript Hooks

One Command for Everything

make api

This executes:

1. swag init → Generates backend/docs/swagger.json from Go comments
2. orval → Generates TypeScript Hooks in frontend/src/shared/api/

Adding a New Endpoint

Step 1: Go Handler with Swagger Comments

// internal/handler/product.go

// GetProducts godoc
// @Summary List all products
// @Description Get all products for the authenticated user
// @Tags products
// @Accept json
// @Produce json
// @Success 200 {array} ProductResponse
// @Failure 401 {object} ErrorResponse
// @Security BearerAuth
// @Router /products [get]
func (h *ProductHandler) GetProducts(w http.ResponseWriter, r *http.Request) {
    // Implementation
}

// CreateProduct godoc
// @Summary Create a product
// @Description Create a new product
// @Tags products
// @Accept json
// @Produce json
// @Param request body CreateProductRequest true "Product data"
// @Success 201 {object} ProductResponse
// @Failure 400 {object} ErrorResponse
// @Failure 401 {object} ErrorResponse
// @Security BearerAuth
// @Router /products [post]
func (h *ProductHandler) CreateProduct(w http.ResponseWriter, r *http.Request) {
    // Implementation
}

Step 2: Define Response/Request Types

// In handler or separate types.go

type ProductResponse struct {
    ID    string  `json:"id" example:"prod_123"`
    Name  string  `json:"name" example:"Widget"`
    Price float64 `json:"price" example:"29.99"`
}

type CreateProductRequest struct {
    Name  string  `json:"name" example:"Widget"`
    Price float64 `json:"price" example:"29.99"`
}

Step 3: Generate API Client

make api

Step 4: Use in Frontend

import { useGetProducts, usePostProducts } from "@/api/endpoints/products/products"

function ProductsPage() {
  const { data, isLoading } = useGetProducts()
  const createProduct = usePostProducts()

  const handleCreate = () => {
    createProduct.mutate({ data: { name: "New", price: 10 } })
  }

  return (...)
}

Swagger Annotation Reference

Annotation	Description
@Summary	Short description
@Description	Detailed description
@Tags	Grouping (becomes folder in endpoints/)
@Accept	Request Content-Type
@Produce	Response Content-Type
@Param	Parameter (body, query, path)
@Success	Success response
@Failure	Error response
@Security	Auth requirement
@Router	HTTP path and method

Generated Files

frontend/src/shared/api/
├── endpoints/
│   ├── products/        # Grouped by @Tags
│   │   └── products.ts  # useGetProducts, usePostProducts, etc.
│   └── users/
│       └── users.ts
├── models/              # TypeScript Types
└── custom-fetch.ts      # Fetch Wrapper with Auth

Important Rules

• Never manually edit generated files
• Always run make api after handler changes
• Tags become folder names → @Tags products → endpoints/products/
• operationId is automatically generated from Router path