Typed REST APIs,
generated from your structs

Annotate a Go struct, run one command, and get real .go files: handlers, queries, validation, filters, pagination and OpenAPI. Nothing is reflected at request time — if a tag is wrong, the build fails, not production.

Get started Browse examples

bookstore generated code is yours

MODEL models/book.go

type Book struct {
    ID    string  `goninja:"list,retrieve"`
    Title string  `goninja:"list,retrieve,create"`
    Price float64 `goninja:"list,retrieve,filter"`
}

GENERATED api/book_generated.go

type BookList struct {
    ID    string  `json:"id"`
    Title string  `json:"title"`
    Price float64 `json:"price"`
}

GET /books typed handlers GORM queries OpenAPI

Tag the struct, run goninja generate, read the Go it wrote.

Code-first

The struct is the single source of truth. No schema files, no YAML, no DSL — a goninja tag on each field decides which operations expose it.

Generated, not reflected

goninja generate writes ordinary Go you can read, diff and step through in a debugger. Zero reflection on the request path.

Plain net/http

Routes mount on an *http.ServeMux. No custom router, no context type of its own, no framework lock-in.

Safe by default

Output types are always separate structs from your GORM model, so a field can never leak into a response just because it exists on the model.

No N+1 by construction

list stays lean and never preloads. retrieve is the detail view and preloads every relation it carries. That split is a guarantee, not a default.

OpenAPI included

Every resource emits an OpenAPI fragment built from the same IR as its handlers, merged into one document and served with Swagger UI or ReDoc.

From struct to running API

Three steps. The middle one is a command; the other two are files you write.

Annotate a model

Each goninja verb decides which operations expose that field. validate tags apply to input only, so Price can never be written negative.

models/book.go

type Book struct {
    ID        string    `gorm:"primaryKey;type:uuid" goninja:"list,retrieve"`
    Title     string    `gorm:"size:200;not null" goninja:"list,retrieve,create,update" validate:"required,max=200"`
    AuthorID  string    `goninja:"list,retrieve,create,update,filter" validate:"required,uuid4"`
    Price     float64   `goninja:"list,retrieve,create,update,filter" validate:"min=0"`
    Published bool      `goninja:"list,retrieve,create,update,filter"`
    CreatedAt time.Time `goninja:"list,retrieve"`
    Author    Author    `goninja:"retrieve"`
}

Generate

This writes one <model>_generated.go per model — output types, handlers, queries and an OpenAPI fragment. Add -watch to regenerate on save.

goninja generate -models-import myapp/models

Mount it

main.go

mux := http.NewServeMux()
app := goninja.NewAPI("Bookstore API", "0.1.0")

app.Mount(mux, api.NewAuthorResource(db), api.NewBookResource(db))
app.MountDocs(mux, "/docs", docsui.SwaggerUI())

http.ListenAndServe(":8080", mux)

That serves a full CRUD surface with filtering, ordering, pagination, validation and live API docs:

curl "localhost:8080/books?published=true&price_min=10&order=-created_at&limit=20"

{
  "items": [{ "id": "9f1c…", "title": "The Go Programming Language", "price": 34.99 }],
  "total": 128,
  "limit": 20,
  "offset": 0
}

Where to go next

Getting Started

Install the CLI and go from an empty module to a running API.

Tag Reference

Every verb and modifier the goninja struct tag accepts.

Filtering & Pagination

Exact-match and range filters, ordering, and the list envelope.

Authentication

Authenticator objects, per-route policy, and the built-in schemes.

Examples

Complete, working projects you can copy from.

Comparison

How goninja differs from Huma, gocrud and gorest.

Typed REST APIs, generated from your structs