newapi

A CLI tool for quickly generating Go API boilerplate code, built on top of gin-gonic and go-bootstrap.

Features

• new command: generate a single API endpoint from command-line flags
• gen command: batch-generate multiple API endpoints from a YAML config file

Each API generates three files automatically:

File	Description
internal/endpoints/{name}_ep.go	Endpoint layer — binds route and HTTP method
internal/services/{name}_srv.go	Service layer — business logic and Swagger annotations
internal/schemas/{name}_schema.go	Schema layer — request/response struct definitions

Note: If a file's first line contains Code generated by newapi. DO NOT EDIT., it will be overwritten on the next run. Otherwise the existing content is preserved. Schema files are never overwritten.

Installation

go install newapi@latest

Or clone and build locally:

git clone https://github.com/johnpoint/newapi.git
cd newapi
go build -o newapi .

Using Docker

Build the image

docker build -t newapi .

Run

Mount your Go project directory (which must contain a go.mod) into the container at /workspace.

new command — generate a single API:

docker run --rm -v $(pwd):/workspace newapi new \
  -n GetUser \
  -d "Get user info" \
  -t user \
  -m get \
  -p /user/{id}

gen command — batch generate from YAML:

docker run --rm -v $(pwd):/workspace newapi gen -c api.yaml

Windows PowerShell: replace $(pwd) with ${PWD}:

docker run --rm -v ${PWD}:/workspace newapi gen -c api.yaml

Quick Start

Initialize a new project and generate your first API in seconds:

mkdir myapp && cd myapp
newapi init myapp          # scaffold project structure + go mod init
newapi new -n Ping -m get -p /ping
go mod tidy
go run ./cmd/server

Usage

init — Initialize a project

newapi init [module-name]

Scaffolds the following layout in the current directory:

.
├── cmd/
│   └── server/
│       └── main.go              ← server entry point
├── internal/
│   ├── endpoints/               ← generated endpoint files
│   ├── services/                ← generated service files
│   └── schemas/                 ← generated schema files
└── go.mod

If module-name is provided, go mod init is run automatically. If go.mod already exists, the module name is read from it.

Examples:

# Fresh directory — creates go.mod automatically
newapi init github.com/yourname/myapp

# Existing Go module — just creates the directory layout
newapi init

new — Create a single API

newapi new [flags]

Flag	Short	Default	Description
--name	-n	TestApi	API name (PascalCase)
--desc	-d	auto generate api	API description
--tag	-t	test	Swagger tag
--method	-m	get	HTTP method
--path	-p	/ping	Request path (supports path params, e.g. /user/{id})

Example:

newapi new -n GetUser -d "Get user info" -t user -m get -p /user/{id}

Generated files:

• internal/endpoints/get_user_ep.go
• internal/services/get_user_srv.go
• internal/schemas/get_user_schema.go

gen — Batch generate APIs

newapi gen -c <config.yaml>

YAML config format:

group:
  - name: user
    apis:
      - name: GetUser
        path: /user/{id}
        desc: Get user info
        method: get
      - name: CreateUser
        path: /user
        desc: Create user
        method: post
  - name: order
    apis:
      - name: GetOrder
        path: /order/{id}
        desc: Get order details
        method: get

Example:

newapi gen -c api.yaml

Dependencies

• cobra — CLI framework
• yaml.v2 — YAML parsing

License

MIT