NetBox Go Client

Auto-generated Go client library for NetBox, generated from NetBox’s OpenAPI specification.

Features

• Automatic Version Detection: Detects NetBox version from the API and generates versioned clients
• Complete API Coverage: Generated from official OpenAPI spec with full type safety
• Multi-Framework Support: Includes server stubs for popular Go web frameworks (gin, echo, chi, fiber, iris, gorilla/mux, net/http)

Prerequisites

• Go 1.21+
• oapi-codegen v2.5.1+
• jq for JSON processing
• goimports for fixing imports
• Access to a NetBox instance (API token required)

Quick Start

1. Start Local NetBox Instance (Optional)

make up

This starts a complete NetBox environment with Docker Compose, including PostgreSQL and Redis.

2. Generate the Client

make generate

This will:

• Fetch the OpenAPI spec from your NetBox instance
• Auto-detect the NetBox version
• Generate a versioned Go client (e.g., v4.2.1/)
• Format and clean up the generated code

3. Use the Generated Client

import "github.com/inngest/netbox-go/v4.2.1"

// Use the generated client...

Configuration

Generate from a Different NetBox Instance

Set environment variables to point to your NetBox instance:

NETBOX_URL=https://netbox.example.com \
NETBOX_TOKEN=your-api-token \
make generate

Environment Variables

• NETBOX_URL - NetBox instance URL (default: http://localhost:8000)
• NETBOX_TOKEN - NetBox API token (default: local dev token)

Development

Commands

• make generate - Generate Go client from NetBox API
• make lint - Run golangci-lint (in versioned directories)
• make up - Start local NetBox with Docker Compose
• make down - Stop local NetBox

Project Structure

.
├── bin/
│   └── generate.sh          # Generation script
├── vX.Y.Z/                  # Generated versioned clients
│   ├── netbox.go            # Generated client code
│   ├── openapi.json         # OpenAPI specification
│   ├── codegen.yml          # Code generation config
│   └── go.mod               # Go module
├── codegen.tpl.yml          # Codegen template
└── compose.yml              # Docker Compose for NetBox

How It Works

1. Fetches the OpenAPI spec from a running NetBox instance
2. Extracts the version from the spec metadata
3. Generates Go client using oapi-codegen
4. Post-processes: fixes nil constants, runs gofmt, and goimports
5. Creates isolated Go module for each version

License

This is auto-generated code. Refer to NetBox’s license for the API specification.