# API Generation

> 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.

- Skill: `diegosouzapw/api-generation` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add diegosouzapw/api-generation`
- Raw SKILL.md: https://api.skillmd.com/api/skills/diegosouzapw/api-generation/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: diegosouzapw (https://skillmd.com/u/diegosouzapw)
- Updated: 2026-09-08
- Page: https://skillmd.com/skills/diegosouzapw/api-generation

---


# 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

```bash
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

```go
// 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

```go
// 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

```bash
make api
```

### Step 4: Use in Frontend

```tsx
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