OpenAPI 3.1 as Native Go Types. Specification as Structs.
Build, read, and write OpenAPI specifications with Go struct literals. No code generation, no builder patterns — the types are the spec.
Get Startedimport "github.com/zoobz-io/openapi"
spec := &openapi.OpenAPI{
OpenAPI: "3.1.0",
Info: openapi.Info{
Title: "Bookstore API",
Version: "1.0.0",
},
Paths: map[string]openapi.PathItem{
"/books": {
Get: &openapi.Operation{
Summary: "List all books",
OperationID: "listBooks",
Responses: map[string]openapi.Response{
"200": {
Description: "A list of books",
Content: map[string]openapi.MediaType{
"application/json": {
Schema: &openapi.Schema{
Type: openapi.NewSchemaType("array"),
Items: &openapi.Schema{Ref: "#/components/schemas/Book"},
},
},
},
},
},
},
},
},
}
// Read existing specs
spec, _ := openapi.FromYAML(data)
spec, _ := openapi.FromJSON(data)
// Write to any format
jsonBytes, _ := spec.ToJSON()
yamlBytes, _ := spec.ToYAML()Why This Package?
The OpenAPI spec expressed directly as Go types. No translation layer, no abstraction overhead.
Direct Spec Mapping
Every Go struct maps 1:1 to the OpenAPI specification. Learning the spec teaches you the package.
Build with Literals
Standard Go struct initialization with IDE autocompletion. No builder patterns or fluent APIs.
Read and Write
FromJSON, FromYAML, ToJSON, ToYAML. Round-trip specs through Go types without loss.
Full 3.1 Coverage
Webhooks, callbacks, discriminators, all OAuth2 flows, and JSON Schema nullable types.
SchemaType Handling
JSON Schema's flexible type field (string or array) handled transparently with IsNullable() and Contains().
Standard Marshalling
Works with json.Encoder and yaml.Encoder directly. Single set of struct tags handles both formats.
Capabilities
Full OpenAPI 3.1 specification support as idiomatic Go types.
| Feature | Description | Link |
|---|---|---|
| Specification Building | Construct full OpenAPI documents from Go struct literals with compile-time field checking. | Quickstart |
| Spec Parsing | Read existing JSON or YAML specifications into fully typed Go structures for programmatic inspection. | Quickstart |
| Components System | Reusable schemas, responses, parameters, security schemes with full $ref support. | Types |
| Security Schemes | HTTP Bearer, API Key, OAuth2 (implicit, password, client credentials, authorization code), and OpenID Connect. | Quickstart |
| Schema Composition | Nullable types, polymorphism with discriminators, and allOf/oneOf/anyOf composition patterns. | Types |
| Vendor Extensions | x-tagGroups and custom extension support for documentation tooling integration. | Types |
Articles
Browse the full openapi documentation.