apic

apic — OpenAPI-to-Server Code Generator

apic is a Go code generator that turns an OpenAPI 3.1 spec (or a JSON config file) into a fully-secured, production-ready HTTP / WebSocket / MCP server plus polyglot clients (Go, React TypeScript, Python, Rust, Zig). You write business logic; everything else — request validation, authentication, rate limiting, TLS, CORS, body caps, audit logging, and typed client bindings — is generated.

Module path: devnw.dev/apic

Note: This repository was relicensed from a proprietary commercial license to Apache-2.0 in June 2026 as part of the public OSS release by CodePros LLC. See CHANGELOG.md and NOTICE for full history.

What gets generated

• REST handlers — Gin-based HTTP server with ServerInterface, generated NOOP stubs, and Valid() method dispatch for every request/response type.
• WebSocket handlers — RFC 6455 stubs with per-connection rate and frame-size limiting.
• MCP tools — JSON-RPC 2.0 tool registry (HTTP, WebSocket, and STDIO transports) for Model Context Protocol integrations.
• GraphQL — schema, HTTP/WS handlers, and in-process resolvers.
• Clients — Go, React TypeScript (TanStack Query), Python stdlib async, Rust (tokio/reqwest), and Zig (std-only synchronous).

All generated code carries composite auth enforcement (api_key, JWT, mTLS, cookie/CSRF, WebAuthn, webhook HMAC), RBAC role hierarchy (admin > manager > user), and FIPS 140-3-capable password hashing.

Requirements

Quick start

1. Clone and install dev toolchain

git clone https://gitlab.com/devnw/codepros/oss/apic.git
cd apic

# Set required env (add to your shell profile)
export GOEXPERIMENT=jsonv2
export GOTOOLCHAIN=go1.26.5

# Install all dev dependencies (oapi-codegen, vacuum, golangci-lint,
# openapi-spec-validator, pre-commit hooks)
make setup

2. Build and test

# Full build: openapi codegen -> tidy -> lint -> fmt -> test
make

# Run tests only
CGO_ENABLED=1 make test

# Run the API server locally (debug mode)
make run

3. Generate a server from your OpenAPI spec

# Regenerate all *.gen.go files from api/cfgs/openapi.yaml
make openapi

4. Generate a server from a JSON config (config-first path)

export GOEXPERIMENT=jsonv2

# Generate into ./gen from the bundled example config
go run ./cmd/apic generate --config configs/example.json --out ./gen

# Generate with tests and fuzz targets
go run ./cmd/apic generate \
  --config configs/example.json \
  --out ./gen \
  --with-tests --with-fuzz

5. Install the apic generator binary

go install devnw.dev/apic/cmd/apic@latest

Private module setup

devnw.dev/log and devnw.dev/bk are public modules that resolve through the public Go module proxy and checksum database — the full repo, including the api/ package and every cmd/ binary, builds and tests credential-free:

go build ./...
go test ./...

Only gitlab.com/devnw/* internal packages remain genuinely private (see .gitlab-ci.yml's GOPRIVATE/GONOSUMDB). If a dependency under that path fails to resolve locally:

export GOPRIVATE=gitlab.com/devnw/*
export GONOSUMDB=gitlab.com/devnw/*
export GOFLAGS=-mod=mod

# Configure authenticated HTTPS access (set GITLAB_USER and GITLAB_PAT in your shell)
git config --global \
  url."https://${GITLAB_USER}:${GITLAB_PAT}@gitlab.com/".insteadOf \
  "https://gitlab.com/"

Repository layout

api/          Framework runtime package — Gin wiring, OIDC, validation, WebSocket/MCP registries
cmd/apic/     Config-driven code generator CLI (reads configs/*.json, writes to gen/)
cmd/gen/      Unified generator entrypoint (--config and/or --openapi); wraps cmd/apic's
              config-driven path and the raw-OpenAPI-spec path behind one binary
cmd/api/      Main API server binary (Cobra CLI, Viper config, dotenv)
cmd/server/   Standalone HTTP server with embedded dev TLS cert
cmd/pipeline/ Orchestrates: gen -> vet -> build -> test -> fuzz -> bench
pkg/httpx/    Token-bucket rate limiter, body size limiter, CORS/security headers
pkg/wsx/      In-repo RFC 6455 WebSocket implementation
pkg/mcpx/     JSON-RPC 2.0 engine for MCP (HTTP, STDIO, WebSocket transports)
pkg/securex/  API key HMAC auth, HS256 JWT, RBAC, CSRF, FIPS-aware password hashing
pkg/obsx/     Request logging, request IDs, expvar metrics, audit log helpers
configs/      Example and reference JSON configs for the config-first generator
api/cfgs/     OpenAPI 3.1 spec and oapi-codegen config
docs/         Full documentation (see below)
tests/        Unit, integration, and security test suites

Documentation

Runtime environment variables

License

Apache-2.0. See LICENSE and NOTICE.

Copyright 2024-2026 CodePros LLC and contributors.