Adding more docs to high level models.

Cleaning things that are not used.

datamodel/constants.go

@@ -21,8 +21,13 @@ import (
 
 // Constants used by utilities to determine the version of OpenAPI that we're referring to.
 const (
-	OAS2  = "oas2"
-	OAS3  = "oas3"
+	// OAS2 represents Swagger Documents
+	OAS2 = "oas2"
+
+	// OAS3 represents OpenAPI 3.0+ Documents
+	OAS3 = "oas3"
+
+	// OAS31 represents OpenAPI 3.1+ Documents
 	OAS31 = "oas3_1"
 )
 

datamodel/high/v3/document.go

@@ -116,6 +116,7 @@ func NewDocument(document *low.Document) *Document {
 	return d
 }
 
+// GoLow returns the low-level Document that was used to create the high level one.
 func (d *Document) GoLow() *low.Document {
 	return d.low
 }

datamodel/high/v3/encoding.go

@@ -9,7 +9,7 @@ import (
 )
 
 // Encoding represents an OpenAPI 3+ Encoding object
-// - https://spec.openapis.org/oas/v3.1.0#encoding-object
+//  - https://spec.openapis.org/oas/v3.1.0#encoding-object
 type Encoding struct {
 	ContentType   string
 	Headers       map[string]*Header

datamodel/high/v3/header.go

@@ -10,6 +10,8 @@ import (
 	low "github.com/pb33f/libopenapi/datamodel/low/v3"
 )
 
+// Header represents a high-level OpenAPI 3+ Header object that is backed by a low-level one.
+//  - https://spec.openapis.org/oas/v3.1.0#header-object
 type Header struct {
 	Description     string
 	Required        bool
@@ -26,6 +28,7 @@ type Header struct {
 	low             *low.Header
 }
 
+// NewHeader creates a new high-level Header instance from a low-level one.
 func NewHeader(header *low.Header) *Header {
 	h := new(Header)
 	h.low = header
@@ -49,10 +52,12 @@ func NewHeader(header *low.Header) *Header {
 	return h
 }
 
+// GoLow returns the low-level Header instance used to create the high-level one.
 func (h *Header) GoLow() *low.Header {
 	return h.low
 }
 
+// ExtractHeaders will extract a hard to navigate low-level Header map, into simple high-level one.
 func ExtractHeaders(elements map[lowmodel.KeyReference[string]]lowmodel.ValueReference[*low.Header]) map[string]*Header {
 	extracted := make(map[string]*Header)
 	for k, v := range elements {

datamodel/high/v3/label_constants.go

@@ -1,10 +0,0 @@
-// Copyright 2022 Princess B33f Heavy Industries / Dave Shanley
-// SPDX-License-Identifier: MIT
-
-package v3
-
-const (
-	NameLabel         = "name"
-	DescriptionLabel  = "description"
-	ExternalDocsLabel = "externalDocs"
-)

datamodel/high/v3/link.go

@@ -8,6 +8,8 @@ import (
 	low "github.com/pb33f/libopenapi/datamodel/low/v3"
 )
 
+// Link represents an OpenAPI 3+ Link object that is backed by a low-level one.
+//  - https://spec.openapis.org/oas/v3.1.0#link-object
 type Link struct {
 	OperationRef string
 	OperationId  string
@@ -19,6 +21,7 @@ type Link struct {
 	low          *low.Link
 }
 
+// NewLink will create a new high-level Link instance from a low-level one.
 func NewLink(link *low.Link) *Link {
 	l := new(Link)
 	l.low = link
@@ -38,6 +41,7 @@ func NewLink(link *low.Link) *Link {
 	return l
 }
 
+// GoLow will return the low-level Link instance used to create the high-level one.
 func (l *Link) GoLow() *low.Link {
 	return l.low
 }

datamodel/high/v3/media_type.go

@@ -11,6 +11,8 @@ import (
 	"sync"
 )
 
+// MediaType represents a high-level OpenAPI MediaType object that is backed by a low-level one.
+//  - https://spec.openapis.org/oas/v3.1.0#media-type-object
 type MediaType struct {
 	Schema     *base.SchemaProxy
 	Example    any