apiary

README

apiary

OpenAPI 3.1 generator for Go: driven by types, not comment soup.

Documentation | Examples | Changelog

---

apiary generates an OpenAPI 3.1 document from annotated Go source code. Your function signatures and struct types are the source of truth, with no schema descriptions duplicated in comments.

// CreateUser registers a new account.
// apiary:operation POST /api/v1/users
// tags: users
// errors: 400,409,500
func (h *UserHandler) CreateUser(ctx context.Context, req CreateUserRequest) (UserDTO, error) {
    // business logic; apiary never touches this
}

The request/response types, the operationId, and the summary (from the godoc) are all inferred. validate:"..." tags become JSON-Schema constraints; pointers become nullable; enums are detected automatically.

Install

go install github.com/yaop-labs/apiary/cmd/apiary@latest

Quickstart

apiary ./...                                   # scan module -> openapi.yaml
apiary -security bearer -out docs/api.yaml ./... # JWT default + custom output
apiary serve ./...                             # live Swagger UI on :8080
apiary -check -out docs/api.yaml ./...          # CI: fail if the spec is stale

Highlights

• Types, not comment soup. Signatures + struct tags are the contract.
• Real go/types analysis. Cross-package, imported, and generic types resolve.
• Rich schemas for free. Validator tags become constraints, with nullable pointers and enums.
• OpenAPI 3.1, operationId for client codegen, JSON or YAML output.
• Honest. Diagnostics for bad signatures, typos, and collisions.

Documentation

Full docs and worked examples (Go input and generated spec) live at yaop-labs.github.io/apiary:

• Annotation format
• Struct tags & Validation
• Security & Frameworks
• CLI reference
• Examples (Go input and generated spec)
• Migrating from swaggo

Stability policy: STABILITY.md. Contributions welcome.