Website · Documentation · Get started · Contribute
Gonex is an API-first Go framework for building modular JSON APIs. It brings together typed request and response schemas, validation, OpenAPI and a project CLI, while keeping your business logic in plain Go. Gonex is free and open source.
Its DRF-inspired workflow starts with your application: install Gonex, generate a project, add modules and develop your API. Persistence, HTTP versioning, gRPC and microservices are available when you need them.
- Install Gonex and its CLI
- Create your first API project
- Build a REST API
- Browse the documentation
- CLI reference
- Server output and logging
Visit the Gonex website for an introduction, code examples and the project journal. Documentation includes a version selector; application HTTP API versions are configured separately.
Requires Go 1.27.2. Install the CLI, then create your own application:
go install github.com/amkargar/gonex/cmd/gonex@main
gonex new shop --module example.com/acme/shop
cd shop
go mod tidy
go tool gonex create module users
go tool gonex check
go tool gonex runEnsure Go's binary installation directory is on PATH. After project creation, use go tool gonex to run the CLI version tracked by your application's go.mod.
Open http://127.0.0.1:8080/users for the starter response:
{"message":"users"}The terminal displays the server URL and request logs. Your API contract is available at http://127.0.0.1:8080/openapi.json. Press Ctrl+C to stop gracefully.
Development status: Gonex has no published release yet. @main installs a development snapshot; use a reviewed commit or an actual published tag to select a particular version. Generated projects pin the installed CLI's resolved framework version. See the release status and changelog.
Define request and response DTOs in schemas.go, map requests in handlers, and register typed endpoints with explicit methods and statuses. Strict JSON binding, validation and OpenAPI 3.1 describe the API you implement. See HTTP contracts.
The CLI creates projects, modules and optional adapters. Generated registries are protected against conflicting edits; handwritten services, schemas and handlers remain yours. The REST API tutorial develops create, list and get actions inside a generated application.
Modules compose services explicitly. Gin HTTP handlers, optional GORM repositories and gRPC adapters translate at the boundaries. Start with a modular monolith and add integrations as the application grows. Read the architecture guide or explore the source examples.
Application startup reports the bound server address. Structured request logs include a request ID, status and duration, with readable development output and JSON in production. Managed resources, health checks, readiness and graceful shutdown support the application lifecycle. See logging and operations.
Hardening, verification commands and outstanding release gates are tracked in the production-readiness reports. The final readiness decision distinguishes passing technical checks from owner/reviewer and release evidence.
Contributions are welcome. Start with Contribute to Gonex for framework setup, architecture, testing and pull requests. The source documentation index contains implementation references and maintenance guides.
Use GitHub Issues to report reproducible bugs or discuss improvements. Review compatibility and upgrades and the release policy when changing public contracts.
Gonex is released under the BSD 3-Clause License.
Create independent HTTP/gRPC/worker services with a strict local catalog, typed clients, gonex doctor and gonex dev. Follow the Orders → Identity tutorial; business mapping stays explicit and contracts must be published before isolated deployment. No framework clone or required distributed runtime is needed.