All v2 high-level docs are completed

Good docs, maketh the tool...

datamodel/high/v2/path_item.go

@@ -8,6 +8,12 @@ import (
 	low "github.com/pb33f/libopenapi/datamodel/low/v2"
 )
 
+// PathItem represents a high-level Swagger / OpenAPI 2 PathItem object backed by a low-level one.
+//
+// Describes the operations available on a single path. A Path Item may be empty, due to ACL constraints.
+// The path itself is still exposed to the tooling, but will not know which operations and parameters
+// are available.
+//  - https://swagger.io/specification/v2/#pathItemObject
 type PathItem struct {
 	Ref        string
 	Get        *Operation
@@ -22,6 +28,7 @@ type PathItem struct {
 	low        *low.PathItem
 }
 
+// NewPathItem will create a new high-level PathItem from a low-level one. All paths are built out asynchronously.
 func NewPathItem(pathItem *low.PathItem) *PathItem {
 	p := new(PathItem)
 	p.low = pathItem
@@ -101,6 +108,7 @@ func NewPathItem(pathItem *low.PathItem) *PathItem {
 	return p
 }
 
+// GoLow returns the low-level PathItem used to create the high-level one.
 func (p *PathItem) GoLow() *low.PathItem {
 	return p.low
 }

datamodel/high/v2/paths.go

@@ -8,12 +8,14 @@ import (
 	low "github.com/pb33f/libopenapi/datamodel/low/v2"
 )
 
+// Paths represents a high-level Swagger / OpenAPI Paths object, backed by a low-level one.
 type Paths struct {
 	PathItems  map[string]*PathItem
 	Extensions map[string]any
 	low        *low.Paths
 }
 
+// NewPaths creates a new high-level instance of Paths from a low-level one.
 func NewPaths(paths *low.Paths) *Paths {
 	p := new(Paths)
 	p.low = paths
@@ -45,6 +47,7 @@ func NewPaths(paths *low.Paths) *Paths {
 	return p
 }
 
+// GoLow returns the low-level Paths instance that backs the high level one.
 func (p *Paths) GoLow() *low.Paths {
 	return p.low
 }

datamodel/high/v2/response.go

@@ -9,6 +9,9 @@ import (
 	low "github.com/pb33f/libopenapi/datamodel/low/v2"
 )
 
+// Response is a representation of a high-level Swagger / OpenAPI 2 Response object, backed by a low-level one.
+// Response describes a single response from an API Operation
+//  - https://swagger.io/specification/v2/#responseObject
 type Response struct {
 	Description string
 	Schema      *base.SchemaProxy
@@ -18,6 +21,7 @@ type Response struct {
 	low         *low.Response
 }
 
+// NewResponse creates a new high-level instance of Response from a low level one.
 func NewResponse(response *low.Response) *Response {
 	r := new(Response)
 	r.low = response
@@ -41,6 +45,7 @@ func NewResponse(response *low.Response) *Response {
 	return r
 }
 
+// GoLow will return the low-level Response instance used to create the high level one.
 func (r *Response) GoLow() *low.Response {
 	return r.low
 }

datamodel/high/v2/responses.go

@@ -8,6 +8,7 @@ import (
 	low "github.com/pb33f/libopenapi/datamodel/low/v2"
 )
 
+// Responses is a high-level representation of a Swagger / OpenAPI 2 Responses object, backed by a low level one.
 type Responses struct {
 	Codes      map[string]*Response
 	Default    *Response
@@ -15,11 +16,13 @@ type Responses struct {
 	low        *low.Responses
 }
 
+// NewResponses will create a new high-level instance of Responses from a low-level one.
 func NewResponses(responses *low.Responses) *Responses {
 	r := new(Responses)
 	r.low = responses
 	r.Extensions = high.ExtractExtensions(responses.Extensions)
 
+	// async function.
 	var buildPath = func(code string, pi *low.Response, rChan chan<- asyncResult[*Response]) {
 		rChan <- asyncResult[*Response]{
 			key:    code,
@@ -31,6 +34,7 @@ func NewResponses(responses *low.Responses) *Responses {
 		r.Default = NewResponse(responses.Default.Value)
 	}
 
+	// run everything async. lots of responses with lots of data are possible.
 	if len(responses.Codes) > 0 {
 		resultChan := make(chan asyncResult[*Response])
 		for k := range responses.Codes {
@@ -51,6 +55,7 @@ func NewResponses(responses *low.Responses) *Responses {
 	return r
 }
 
+// GoLow will return the low-level object used to create the high-level one.
 func (r *Responses) GoLow() *low.Responses {
 	return r.low
 }

datamodel/high/v2/responses_definitions.go

@@ -5,14 +5,23 @@ package v2
 
 import low "github.com/pb33f/libopenapi/datamodel/low/v2"
 
+// ResponsesDefinitions is a high-level representation of a Swagger / OpenAPI 2 Responses Definitions object.
+// that is backed by a low-level one.
+//
+// ResponsesDefinitions is an object to hold responses to be reused across operations. Response definitions can be
+// referenced to the ones defined here. It does not define global operation responses
+//  - https://swagger.io/specification/v2/#responsesDefinitionsObject
 type ResponsesDefinitions struct {
 	Definitions map[string]*Response
 	low         *low.ResponsesDefinitions
 }
 
+// NewResponsesDefinitions will create a new high-level instance of ResponsesDefinitions from a low-level one.
 func NewResponsesDefinitions(responsesDefinitions *low.ResponsesDefinitions) *ResponsesDefinitions {
 	rd := new(ResponsesDefinitions)
 	rd.low = responsesDefinitions
+
+	// build everything async.
 	responses := make(map[string]*Response)
 	var buildResp = func(name string, resp *low.Response, rChan chan<- asyncResult[*Response]) {
 		rChan <- asyncResult[*Response]{
@@ -37,6 +46,7 @@ func NewResponsesDefinitions(responsesDefinitions *low.ResponsesDefinitions) *Re
 	return rd
 }
 
+// GoLow returns the low-level ResponsesDefinitions used to create the high-level one.
 func (r *ResponsesDefinitions) GoLow() *low.ResponsesDefinitions {
 	return r.low
 }

datamodel/high/v2/scopes.go

@@ -7,11 +7,16 @@ import (
 	low "github.com/pb33f/libopenapi/datamodel/low/v2"
 )
 
+// Scopes is a high-level representation of a Swagger / OpenAPI 2 OAuth2 Scopes object, that is backed by a low-level one.
+//
+// Scopes lists the available scopes for an OAuth2 security scheme.
+//  - https://swagger.io/specification/v2/#scopesObject
 type Scopes struct {
 	Values map[string]string
 	low    *low.Scopes
 }
 
+// NewScopes creates a new high-level instance of Scopes from a low-level one.
 func NewScopes(scopes *low.Scopes) *Scopes {
 	s := new(Scopes)
 	s.low = scopes
@@ -23,6 +28,7 @@ func NewScopes(scopes *low.Scopes) *Scopes {
 	return s
 }
 
+// GoLow returns the low-level instance of Scopes used to create the high-level one.
 func (s *Scopes) GoLow() *low.Scopes {
 	return s.low
 }

datamodel/high/v2/security_definitions.go

@@ -5,11 +5,18 @@ package v2
 
 import low "github.com/pb33f/libopenapi/datamodel/low/v2"
 
+// SecurityDefinitions is a high-level representation of a Swagger / OpenAPI 2 Security Definitions object, that
+// is backed by a low-level one.
+//
+// A declaration of the security schemes available to be used in the specification. This does not enforce the security
+// schemes on the operations and only serves to provide the relevant details for each scheme
+//  - https://swagger.io/specification/v2/#securityDefinitionsObject
 type SecurityDefinitions struct {
 	Definitions map[string]*SecurityScheme
 	low         *low.SecurityDefinitions
 }
 
+// NewSecurityDefinitions creates a new high-level instance of a SecurityDefinitions from a low-level one.
 func NewSecurityDefinitions(definitions *low.SecurityDefinitions) *SecurityDefinitions {
 	sd := new(SecurityDefinitions)
 	sd.low = definitions
@@ -21,6 +28,7 @@ func NewSecurityDefinitions(definitions *low.SecurityDefinitions) *SecurityDefin
 	return sd
 }
 
+// GoLow returns the low-level SecurityDefinitions instance used to create the high-level one.
 func (sd *SecurityDefinitions) GoLow() *low.SecurityDefinitions {
 	return sd.low
 }

datamodel/high/v2/security_requirement.go

@@ -5,11 +5,19 @@ package v2
 
 import low "github.com/pb33f/libopenapi/datamodel/low/v2"
 
+// SecurityRequirement is a high-level representation of a Swagger / OpenAPI 2 SecurityRequirement object.
+//
+// SecurityRequirement lists the required security schemes to execute this operation. The object can have multiple
+// security schemes declared in it which are all required (that is, there is a logical AND between the schemes).
+//
+// The name used for each property MUST correspond to a security scheme declared in the Security Definitions
+//  - https://swagger.io/specification/v2/#securityDefinitionsObject
 type SecurityRequirement struct {
 	Requirements map[string][]string
 	low          *low.SecurityRequirement
 }
 
+// NewSecurityRequirement creates a new high-level SecurityRequirement from a low-level one.
 func NewSecurityRequirement(req *low.SecurityRequirement) *SecurityRequirement {
 	r := new(SecurityRequirement)
 	r.low = req
@@ -26,6 +34,7 @@ func NewSecurityRequirement(req *low.SecurityRequirement) *SecurityRequirement {
 	return r
 }
 
+// GoLow returns the low-level SecurityRequirement used to create the high-level one.
 func (s *SecurityRequirement) GoLow() *low.SecurityRequirement {
 	return s.low
 }

datamodel/high/v2/security_scheme.go

@@ -8,6 +8,13 @@ import (
 	low "github.com/pb33f/libopenapi/datamodel/low/v2"
 )
 
+// SecurityScheme is a high-level representation of a Swagger / OpenAPI 2 SecurityScheme object
+// backed by a low-level one.
+//
+// SecurityScheme allows the definition of a security scheme that can be used by the operations. Supported schemes are
+// basic authentication, an API key (either as a header or as a query parameter) and OAuth2's common flows
+// (implicit, password, application and access code)
+//  - https://swagger.io/specification/v2/#securityDefinitionsObject
 type SecurityScheme struct {
 	Type             string
 	Description      string
@@ -21,6 +28,7 @@ type SecurityScheme struct {
 	low              *low.SecurityScheme
 }
 
+// NewSecurityScheme creates a new instance of SecurityScheme from a low-level one.
 func NewSecurityScheme(securityScheme *low.SecurityScheme) *SecurityScheme {
 	s := new(SecurityScheme)
 	s.low = securityScheme
@@ -52,6 +60,7 @@ func NewSecurityScheme(securityScheme *low.SecurityScheme) *SecurityScheme {
 	return s
 }
 
+// GoLow returns the low-level SecurityScheme that was used to create the high-level one.
 func (s *SecurityScheme) GoLow() *low.SecurityScheme {
 	return s.low
 }