Types

This document outlines the type hierarchy. For complete field documentation, see pkg.go.dev.

Root Object

OpenAPI
├── Info
│   ├── Contact
│   └── License
├── Server[]
│   └── ServerVariable (map)
├── Paths (map)
│   └── PathItem
├── Webhooks (map)
│   └── PathItem
├── Components
├── Security[]
│   └── SecurityRequirement
├── Tags[]
│   └── Tag
├── TagGroups[] (x-tagGroups)
│   └── TagGroup
└── ExternalDocumentation

Path and Operations

PathItem
├── Get, Post, Put, Delete, Patch, Options, Head → Operation
├── Parameters[]
├── Servers[]
├── Ref (for $ref)
├── Summary
└── Description

Operation
├── OperationID
├── Summary, Description
├── Tags[]
├── Parameters[]
├── RequestBody
├── Responses (map)
├── Callbacks (map)
├── Security[]
├── Servers[]
├── ExternalDocs
└── Deprecated

Request and Response

RequestBody
├── Content (map) → MediaType
├── Description
├── Required
└── Ref

Response
├── Description
├── Headers (map) → Header
├── Content (map) → MediaType
├── Links (map) → Link
└── Ref

MediaType
├── Schema
├── Example
├── Examples (map) → Example
└── Encoding (map)

Schema

The Schema type represents JSON Schema with OpenAPI extensions:

Schema
├── Type → SchemaType
├── Format
├── Properties (map) → Schema
├── Items → Schema
├── Required[]
├── AllOf[], OneOf[], AnyOf[] → Schema
├── Not → Schema
├── Discriminator
├── Ref
├── Title, Description
├── Default, Const, Example
├── Enum[]
├── Minimum, Maximum, ExclusiveMinimum, ExclusiveMaximum
├── MinLength, MaxLength
├── Pattern
├── MinItems, MaxItems, UniqueItems
├── MinProperties, MaxProperties
├── AdditionalProperties
├── ReadOnly, WriteOnly, Deprecated
├── XML
└── ExternalDocs

SchemaType

Handles the JSON Schema type field, which can be a string or array:

// Single type
Type: openapi.NewSchemaType("string")

// Multiple types (nullable)
Type: openapi.NewSchemaTypes([]string{"string", "null"})

// Query methods
schemaType.IsEmpty()     // True if no type set
schemaType.IsArray()     // True if multiple types
schemaType.IsNullable()  // True if contains "null"
schemaType.Contains("string")
schemaType.String()      // First/only type as string
schemaType.Strings()     // All types as slice

Components

Reusable objects referenced via $ref:

Components
├── Schemas (map) → Schema
├── Responses (map) → Response
├── Parameters (map) → Parameter
├── Examples (map) → Example
├── RequestBodies (map) → RequestBody
├── Headers (map) → Header
├── SecuritySchemes (map) → SecurityScheme
├── Links (map) → Link
├── Callbacks (map) → Callback
└── PathItems (map) → PathItem

Security

SecurityScheme
├── Type ("apiKey", "http", "oauth2", "openIdConnect")
├── Description
├── Name, In (for apiKey)
├── Scheme, BearerFormat (for http)
├── Flows → OAuthFlows (for oauth2)
└── OpenIDConnectURL (for openIdConnect)

OAuthFlows
├── Implicit → OAuthFlow
├── Password → OAuthFlow
├── ClientCredentials → OAuthFlow
└── AuthorizationCode → OAuthFlow

OAuthFlow
├── AuthorizationURL
├── TokenURL
├── RefreshURL
└── Scopes (map)

SecurityRequirement = map[string][]string

Supporting Types

Parameter
├── Name, In, Description
├── Required, Deprecated
├── Schema or Content
├── Style, Explode
├── Example, Examples
└── Ref

Header
├── (Same fields as Parameter, minus Name and In)
└── Ref

Link
├── OperationRef or OperationID
├── Parameters (map)
├── RequestBody
├── Description
├── Server
└── Ref

Callback = map[string]PathItem

Tag
├── Name
├── Description
└── ExternalDocs

TagGroup (x-tagGroups vendor extension)
├── Name
└── Tags[]

ExternalDocumentation
├── URL
└── Description

Discriminator
├── PropertyName
└── Mapping (map)

XML
├── Name, Namespace, Prefix
├── Attribute
└── Wrapped

Encoding
├── ContentType
├── Headers (map)
├── Style, Explode
└── AllowReserved

Example
├── Summary, Description
├── Value or ExternalValue
└── Ref

Reference Pattern

Most types support $ref via a Ref field. When Ref is set, other fields should be empty:

// Inline definition
schema := &openapi.Schema{
    Type: openapi.NewSchemaType("object"),
    Properties: map[string]*openapi.Schema{...},
}

// Reference
schema := &openapi.Schema{
    Ref: "#/components/schemas/User",
}

Reference resolution is not handled by this package—that's a concern for tooling built on top of these types.