Update data structure and logic to handle both Swagger 2 and OpenAPI 3

README.md

@@ -1,4 +1,4 @@
-# OpenAPI v2 object model [![Build Status](https://github.com/go-openapi/spec/actions/workflows/go-test.yml/badge.svg)](https://github.com/go-openapi/spec/actions?query=workflow%3A"go+test") [![codecov](https://codecov.io/gh/go-openapi/spec/branch/master/graph/badge.svg)](https://codecov.io/gh/go-openapi/spec)
+# OpenAPI v2/v3 object model [![Build Status](https://github.com/go-openapi/spec/actions/workflows/go-test.yml/badge.svg)](https://github.com/go-openapi/spec/actions?query=workflow%3A"go+test") [![codecov](https://codecov.io/gh/go-openapi/spec/branch/master/graph/badge.svg)](https://codecov.io/gh/go-openapi/spec)
 
 [![Slack Status](https://slackin.goswagger.io/badge.svg)](https://slackin.goswagger.io)
 [![license](http://img.shields.io/badge/license-Apache%20v2-orange.svg)](https://raw.githubusercontent.com/go-openapi/spec/master/LICENSE)
@@ -15,7 +15,7 @@ This library ships under the [SPDX-License-Identifier: Apache-2.0](./LICENSE).
 
 * What does this do?
 
-> 1. This package knows how to marshal and unmarshal Swagger API specifications into a golang object model
+> 1. This package knows how to marshal and unmarshal Swagger and OpenAPI v3  API specifications into a golang object model
 > 2. It knows how to resolve $ref and expand them to make a single root document
 
 * How does it play with the rest of the go-openapi packages ?
@@ -27,12 +27,14 @@ This library ships under the [SPDX-License-Identifier: Apache-2.0](./LICENSE).
 
 * Does this library support OpenAPI 3?
 
-> No.
-> This package currently only supports OpenAPI 2.0 (aka Swagger 2.0).
-> There is no plan to make it evolve toward supporting OpenAPI 3.x.
-> This [discussion thread](https://github.com/go-openapi/spec/issues/21) relates the full story.
->
-> An early attempt to support Swagger 3 may be found at: https://github.com/go-openapi/spec3
+> **Yes!**
+> This package supports both OpenAPI 2.0 (aka Swagger 2.0) and OpenAPI 3.x (3.2.0).
+> Key changes in v3:
+> - `swagger: "2.0"` → `openapi: "3.x.x"`
+> - `definitions`, `parameters`, `responses` → `components/*`
+> - `host`, `basePath`, `schemes` → `servers[]`
+> - Body/form parameters → `requestBody`
+> - Response schemas → `content` with media types
 
 * Does the unmarshaling support YAML?
 

cache.go

@@ -69,8 +69,10 @@ func initResolutionCache() {
 
 func defaultResolutionCache() *simpleCache {
 	return &simpleCache{store: map[string]any{
-		"http://swagger.io/v2/schema.json":       MustLoadSwagger20Schema(),
-		"http://json-schema.org/draft-04/schema": MustLoadJSONSchemaDraft04(),
+		"http://swagger.io/v2/schema.json":                     MustLoadSwagger20Schema(),
+		"http://json-schema.org/draft-04/schema":               MustLoadJSONSchemaDraft04(),
+		"https://spec.openapis.org/oas/3.2/schema/2025-09-17":  MustLoadOpenAPI32Schema(),
+		"https://spec.openapis.org/oas/3.2/schema/2025-09-17#": MustLoadOpenAPI32Schema(),
 	}}
 }
 

components.go

@@ -0,0 +1,174 @@
+// SPDX-FileCopyrightText: Copyright 2015-2025 go-swagger maintainers
+// SPDX-License-Identifier: Apache-2.0
+
+package spec
+
+import (
+	"encoding/json"
+
+	"github.com/go-openapi/jsonpointer"
+	"github.com/go-openapi/swag/jsonutils"
+)
+
+// Components holds a set of reusable objects for different aspects of the OAS.
+// All objects defined within the components object will have no effect on the API
+// unless they are explicitly referenced from properties outside the components object.
+//
+// For more information: https://spec.openapis.org/oas/v3.1.0#components-object
+type Components struct {
+	VendorExtensible
+	ComponentsProps
+}
+
+// ComponentsProps describes the properties of a Components object
+type ComponentsProps struct {
+	Schemas         map[string]Schema         `json:"schemas,omitempty"`
+	Responses       map[string]Response       `json:"responses,omitempty"`
+	Parameters      map[string]Parameter      `json:"parameters,omitempty"`
+	Examples        map[string]Example        `json:"examples,omitempty"`
+	RequestBodies   map[string]RequestBody    `json:"requestBodies,omitempty"`
+	Headers         map[string]Header         `json:"headers,omitempty"`
+	SecuritySchemes map[string]SecurityScheme `json:"securitySchemes,omitempty"`
+	Links           map[string]Link           `json:"links,omitempty"`
+	Callbacks       map[string]Callback       `json:"callbacks,omitempty"`
+}
+
+// JSONLookup look up a value by the json property name
+func (c Components) JSONLookup(token string) (any, error) {
+	if ex, ok := c.Extensions[token]; ok {
+		return &ex, nil
+	}
+	r, _, err := jsonpointer.GetForToken(c.ComponentsProps, token)
+	return r, err
+}
+
+// MarshalJSON marshals this to JSON
+func (c Components) MarshalJSON() ([]byte, error) {
+	b1, err := json.Marshal(c.ComponentsProps)
+	if err != nil {
+		return nil, err
+	}
+	b2, err := json.Marshal(c.VendorExtensible)
+	if err != nil {
+		return nil, err
+	}
+	return jsonutils.ConcatJSON(b1, b2), nil
+}
+
+// UnmarshalJSON unmarshals this from JSON
+func (c *Components) UnmarshalJSON(data []byte) error {
+	if err := json.Unmarshal(data, &c.ComponentsProps); err != nil {
+		return err
+	}
+	return json.Unmarshal(data, &c.VendorExtensible)
+}
+
+// Link represents a possible design-time link for a response.
+//
+// For more information: https://spec.openapis.org/oas/v3.1.0#link-object
+type Link struct {
+	Refable
+	VendorExtensible
+	LinkProps
+}
+
+// LinkProps describes the properties of a Link
+type LinkProps struct {
+	OperationRef string         `json:"operationRef,omitempty"`
+	OperationID  string         `json:"operationId,omitempty"`
+	Parameters   map[string]any `json:"parameters,omitempty"`
+	RequestBody  any            `json:"requestBody,omitempty"`
+	Description  string         `json:"description,omitempty"`
+	Server       *Server        `json:"server,omitempty"`
+}
+
+// JSONLookup look up a value by the json property name
+func (l Link) JSONLookup(token string) (any, error) {
+	if ex, ok := l.Extensions[token]; ok {
+		return &ex, nil
+	}
+	r, _, err := jsonpointer.GetForToken(l.LinkProps, token)
+	return r, err
+}
+
+// MarshalJSON marshals this to JSON
+func (l Link) MarshalJSON() ([]byte, error) {
+	b1, err := json.Marshal(l.Refable)
+	if err != nil {
+		return nil, err
+	}
+	b2, err := json.Marshal(l.LinkProps)
+	if err != nil {
+		return nil, err
+	}
+	b3, err := json.Marshal(l.VendorExtensible)
+	if err != nil {
+		return nil, err
+	}
+	return jsonutils.ConcatJSON(b1, b2, b3), nil
+}
+
+// UnmarshalJSON unmarshals this from JSON
+func (l *Link) UnmarshalJSON(data []byte) error {
+	if err := json.Unmarshal(data, &l.Refable); err != nil {
+		return err
+	}
+	if err := json.Unmarshal(data, &l.LinkProps); err != nil {
+		return err
+	}
+	return json.Unmarshal(data, &l.VendorExtensible)
+}
+
+// Callback is a map of possible out-of band callbacks related to the parent operation.
+//
+// For more information: https://spec.openapis.org/oas/v3.1.0#callback-object
+type Callback struct {
+	Refable
+	VendorExtensible
+	CallbackProps
+}
+
+// CallbackProps describes the properties of a Callback
+type CallbackProps struct {
+	Expressions map[string]PathItem `json:"-"`
+}
+
+// JSONLookup look up a value by the json property name
+func (c Callback) JSONLookup(token string) (any, error) {
+	if ex, ok := c.Extensions[token]; ok {
+		return &ex, nil
+	}
+	if pi, ok := c.Expressions[token]; ok {
+		return pi, nil
+	}
+	r, _, err := jsonpointer.GetForToken(c.CallbackProps, token)
+	return r, err
+}
+
+// MarshalJSON marshals this to JSON
+func (c Callback) MarshalJSON() ([]byte, error) {
+	b1, err := json.Marshal(c.Refable)
+	if err != nil {
+		return nil, err
+	}
+	b2, err := json.Marshal(c.Expressions)
+	if err != nil {
+		return nil, err
+	}
+	b3, err := json.Marshal(c.VendorExtensible)
+	if err != nil {
+		return nil, err
+	}
+	return jsonutils.ConcatJSON(b1, b2, b3), nil
+}
+
+// UnmarshalJSON unmarshals this from JSON
+func (c *Callback) UnmarshalJSON(data []byte) error {
+	if err := json.Unmarshal(data, &c.Refable); err != nil {
+		return err
+	}
+	if err := json.Unmarshal(data, &c.Expressions); err != nil {
+		return err
+	}
+	return json.Unmarshal(data, &c.VendorExtensible)
+}

embed.go

@@ -18,3 +18,7 @@ func jsonschemaDraft04JSONBytes() ([]byte, error) {
 func v2SchemaJSONBytes() ([]byte, error) {
 	return assets.ReadFile(path.Join("schemas", "v2", "schema.json"))
 }
+
+func v3SchemaJSONBytes() ([]byte, error) {
+	return assets.ReadFile(path.Join("schemas", "v3", "schema.json"))
+}