libopenapi

To render OpenAPI oneOf as a typed union in Go, the schema must have an explicit discriminator or share an inferable const discriminator property.

When generating OpenAPI from Go reflection, you must register interface variants and their discriminator mapping using WithOneOfTypes and WithDiscriminatorMapping.

gen := golang.NewGenerator(
    golang.WithOneOfTypes((*PaymentMethod)(nil), Card{}, Bank{}),
    golang.WithDiscriminatorMapping((*PaymentMethod)(nil), "object", map[string]string{
        "card": "#/components/schemas/Card",
        "bank": "#/components/schemas/Bank",
    }),
)

The libopenapi library uses a dual-layer approach to handle OpenAPI specifications:

1. High-level (Porcelain) API: Provides strongly typed, easy-to-use models (e.g., v3high.Document) for navigating and manipulating the specification. This is what most developers use for business logic.
2. Low-level (Plumbing) API: Provides access to the raw data, including comments, line numbers, and column numbers. This is essential for tools that need to perform precise edits or maintain formatting.

Every high-level type provides a GoLow() method. Calling this allows you to 'drop down' from the high-level model to the low-level data for more granular operations. When you use RenderAndReload(), the library uses the high-level model to generate new bytes and then re-parses them to rebuild the low-level index, ensuring that line/column information remains accurate even after mutations.

Schema-valued additionalProperties renders as an AdditionalProperties map[string]T field in Go with the json:"-" tag. Generated objects receive MarshalJSON and UnmarshalJSON methods to ensure unknown properties are captured in the map.

Use WithAdditionalPropertiesMethods(false) if you want the struct field but prefer to provide your own JSON marshaling logic.

The generator handles common Go initialisms (e.g., ID, URL, UUID) automatically.

Customization Options:

• Nesting Delimiters: Use WithNestedTypeNameDelimiter(string) to change the default _ delimiter for nested types (e.g., Order_PaymentSource). Passing an empty string produces compact names like OrderPaymentSource.
• Collision Resolution: Colliding OpenAPI keys (e.g., user-id and user_id) are resolved using a double underscore suffix (e.g., UserID__2).
• Custom Resolvers: Use WithTypeNameResolver, WithFieldNameResolver, WithEnumValueNameResolver, or WithNameResolver for project-specific naming requirements.

To work with an OpenAPI or Swagger specification, you must first create a Document instance. You can do this by passing a []byte array containing the specification (either JSON or YAML) to NewDocument or NewDocumentWithConfiguration.

Note that NewDocument does not automatically follow file or remote references. If you need to control how references are resolved (e.g., allowing or disallowing local/remote files), use NewDocumentWithConfiguration and provide a *datamodel.DocumentConfiguration.

import "github.com/pb33f/libopenapi"

// Basic usage
doc, err := libopenapi.NewDocument(specBytes)
if err != nil {
    // handle error
}

// Usage with configuration for references
config := &datamodel.DocumentConfiguration{
    AllowFileReferences: true,
    AllowRemoteReferences: false,
}
doc, err = libopenapi.NewDocumentWithConfiguration(specBytes, config)

When generating OpenAPI schemas from Go types, use slice-based variants for package-level helpers that require configuration options.

Example of using SchemasFromTypesWithOptions to register interface variants for polymorphism:

set, err := golang.SchemasFromTypesWithOptions(
    []reflect.Type{reflect.TypeOf(Customer{})},
    golang.WithOneOfTypes((*PaymentMethod)(nil), Card{}, Bank{}),
)

You can map custom scalar aliases to specific OpenAPI schemas without adding methods to the Go types by using golang.NewGenerator with WithTypeSchema.

gen := golang.NewGenerator(
    golang.WithTypeSchema(reflect.TypeOf(CustomerID("")), customerIDSchema),
)

Use the golang package to convert OpenAPI schema/component models into Go source code. You can generate a single schema using RenderSchema or an ordered map of components using Generator.RenderSchemas.

RenderSchemas returns a *GeneratedFile containing:

• PackageName: The name of the generated package.
• Source: The gofmt-formatted Go source code.
• SchemaMetadata: An optional schema_metadata.go sidecar source (if enabled).
• Types: Top-level generated type names and kinds.
• Diagnostics: Notable generator decisions or limitations.

source, err := golang.RenderSchema("Pet", schemaProxy)
if err != nil {
    return err
}
fmt.Println(string(source))

Convert Go reflection types into OpenAPI schema/component models.

• Use SchemaFromType for a single schema.
• Use SchemasFromTypes to create a reusable component graph.

SchemaSet.Root contains the first requested root. SchemaSet.Components contains named structs, registered interface unions, and reusable model shapes. Nested named model references are rendered as #/components/schemas/... refs.

Note on Nullability: The generator uses JSON Schema 2020-12 native nullability (type: [T, "null"]) rather than the OpenAPI 3.0 nullable: true keyword.

set, err := golang.SchemasFromTypes(reflect.TypeOf(Customer{}))
if err != nil {
    return err
}
root := set.Root
components := set.Components

Diagnostics are not validation errors; they report lossy model-shape choices, unsupported keywords, or naming collisions. Diagnostics include a stable Code, a Path, and a Message. Callers should branch on the Code rather than the message text.

Common Diagnostic Codes:

• DiagnosticComponentNameCollision: Colliding component names.
• DiagnosticExternalReference: Use of external $ref values.
• DiagnosticFieldNameCollision: Colliding field names.
• DiagnosticPatternProperties: patternProperties do not map cleanly to Go fields.
• DiagnosticTypeNameCollision: Colliding type names.
• DiagnosticValidationKeyword: Unsupported validation-only keywords.