create-gin-api

create-gin-api is a Go CLI scaffold. It writes a Gin API directory that compiles as is: the handler → service → database / redis layering is already in place, along with environment variables, a Makefile, Air, Swagger, and Docker Compose.

DATABASE_URL and REDIS_URL are optional when running locally; Compose injects the Postgres and Redis service addresses on startup.

Requires Go 1.25 or later. Install the latest semver tag:

go install github.com/oriensx/create-gin-api@latest

After pushing a new tag with git push origin vX.Y.Z, you need to run go install …@latest again locally — an installed binary is not replaced automatically. If you need it right away, try GOPROXY=direct.

Or clone the repo and run it locally:

git clone https://github.com/oriensx/create-gin-api.git
cd create-gin-api
go install .
# or: go run . <name>

Run it in a TTY without a project nameand it enters interactive mode: it asks for name, module, parent directory, title, and description in turn, using the default shown in parentheses when you press enter. Flags you already passed become the defaults.

create-gin-api
create-gin-api my-api
create-gin-api -module github.com/acme/my-api my-api
create-gin-api -out ~/work -title "Order Service API" order-svc

Flags go before <name>. The project name must match ^[a-z][a-z0-9-]*$. When it is not a TTY and no <name> is given, it prints usage and exits.

cd my-api
cp .env.example .env
make run              # start locally
make docker-up        # api + Postgres + Redis
make swagger          # if swag was not on PATH at generation time
make docker-down      # stop Compose

Optional development tools:

go install github.com/air-verse/air@latest
go install github.com/swaggo/swag/cmd/swag@latest

After writing files it runs go mod tidy; if swag is installed it goes on to generate docs. Any failing step exits non-zero and never prints Success. Child process logs stay quiet by default and only surface on failure.

Progress and success text follow create-next-app closely: checked-off steps, command explanations, and a suggested cd / make run. Set NO_COLOR to turn colors off.

✔ Creating project in /path/my-api
✔ Downloading Go modules
✔ Generating Swagger docs

Success! Created my-api at /path/my-api
  module  my-api
  title   My Api API

Inside that directory, you can run several commands:

  make run
    Start the API server locally.

  make docker-up
    Build and start api + Postgres + Redis.

We suggest that you begin by typing:

  cd my-api
  cp .env.example .env
  make run

The default layout looks roughly like this:

cmd/server/               # entrypoint (package main)
docs/                     # OpenAPI generated by swag
internal/
  config/                 # environment variables
  database/               # GORM + Postgres
  redis/                  # go-redis
  handler/                # HTTP handlers
  logger/                 # Zap
  router/                 # route wiring
  service/                # business logic
Dockerfile                # multi-stage image
docker-compose.yml        # api + Postgres + Redis
Makefile / .air.toml / .env.example

Make targets: tidy, build, run, dev, swagger, test, docker-build, docker-up, docker-down.

make docker-up builds the API image and starts Postgres 16 and Redis 7, then brings up the api only after health checks pass. Inside Compose, DATABASE_URL / REDIS_URL point at the service names postgres / redis. The host port defaults to 8080 (override the published mapping with the PORT environment variable).

• Gin
• GORM / Postgres
• Redis
• Zap
• Air
• Swagger
• Docker

To change what gets generated, edit internal/scaffold/template/ in the scaffold repo. Maintenance notes live in DEVELOP.md.

MIT. Source: github.com/oriensx/create-gin-api