importer-msgraph-metadata: add more doc comments, remove resource bla…

…cklist since this is now covered by workarounds

tools/importer-msgraph-metadata/components/parser/resourceids.go

@@ -76,6 +76,8 @@ func (r ResourceId) ID() string {
 	return "/" + strings.Join(segments, "/")
 }
 
+// DataApiSdkResourceId converts the internal ResourceId representation to a Data API SDK ResourceID, so it can be
+// persisted to the Data API Definitions.
 func (r ResourceId) DataApiSdkResourceId() (*sdkModels.ResourceID, error) {
 	sdkSegments := make([]sdkModels.ResourceIDSegment, 0, len(r.Segments))
 

tools/importer-msgraph-metadata/components/parser/resources.go

@@ -10,32 +10,99 @@ import (
 	sdkModels "github.com/hashicorp/pandora/tools/data-api-sdk/v1/models"
 )
 
+type Resources map[string]*Resource
+
 type Resource struct {
-	Name       string
-	Category   string
-	Version    string
-	Service    string
-	Paths      []ResourceId
+	// The name of this resource
+	Name string
+
+	// The category for this resource, used to group resources together in the same SDK package
+	Category string
+
+	// The API version for this resource
+	Version string
+
+	// The name of the service associated with this resource
+	Service string
+
+	// All known paths for this resource, used for category matching between different resources
+	Paths []ResourceId
+
+	// Supported operations for this resource
 	Operations []Operation
 }
 
 type Operation struct {
-	Name               string
-	Description        string
-	Type               OperationType
-	Method             string
-	ResourceId         *ResourceId
-	UriSuffix          *string
+	// The full name of this operation, which should be unique across resources (at least in the same category) so
+	// prevent clobbering when resources/operations are grouped into an SDK package
+	Name string
+
+	// Optional description which can be added to the generated SDK model as a comment
+	Description string
+
+	// The type of this operation, initially determined from the HTTP method
+	Type OperationType
+
+	// The HTTP method for this operation
+	Method string
+
+	// The resource ID that comprises the first part of the URI for this operation
+	ResourceId *ResourceId
+
+	// The remainder of the URI after the resource ID
+	UriSuffix *string
+
+	// The content-type of the request body
 	RequestContentType *string
-	RequestModel       *string
-	RequestHeaders     *Headers
-	RequestParams      *Params
-	RequestType        *DataType
-	Responses          Responses
-	PaginationField    *string
-	Tags               []string
+
+	// The model that describes the request body
+	RequestModel *string
+
+	// Any user-specified HTTP headers supported for the request
+	RequestHeaders *Headers
+
+	// Any user-specified query string parameters support for the request
+	RequestParams *Params
+
+	// The internal data type for the request, used when the content type is JSON or XML,
+	// and the request is not described by a model
+	RequestType *DataType
+
+	// The expected *success* responses for this operation
+	Responses Responses
+
+	// When the content type is JSON or XML, and this is a List operation, the name of the field
+	// that specifies a URL to retrieve the next page of results
+	PaginationField *string
+
+	// OpenAPI3 tags for this operation, used to reconcile operations to services
+	Tags []string
+}
+
+type Responses []Response
+
+type Response struct {
+	// The HTTP status code associated with this expected response
+	Status int
+
+	// The expected content type for this resource
+	ContentType *string
+
+	// Specifies a referenced model or constant for the response, noting that this
+	// should be the full type name from the spec prior to normalizing
+	ReferenceName *string
+
+	// The internal data type for the response, used when the content type is JSON or XML,
+	// and the response is not described by a model
+	Type *DataType
+
+	// Model and Constant are used internally for ad-hoc response models
+	Model    *Model
+	Constant *Constant
 }
 
+type Headers []Header
+
 type Header struct {
 	Name string
 	Type *DataType
@@ -53,7 +120,7 @@ func (h Header) DataApiSdkObjectDefinition() (*sdkModels.SDKOperationOptionObjec
 	}, nil
 }
 
-type Headers []Header
+type Params []Param
 
 type Param struct {
 	Name     string
@@ -89,28 +156,6 @@ func (p Param) DataApiSdkObjectDefinition() (*sdkModels.SDKOperationOptionObject
 	}, nil
 }
 
-type Params []Param
-
-type Response struct {
-	Status        int
-	ContentType   *string
-	ReferenceName *string
-	Type          *DataType
-	Model         *Model
-	Constant      *Constant
-}
-
-type Responses []Response
-
-func (rs Responses) FindModelName() *string {
-	for _, r := range rs {
-		if r.ReferenceName != nil {
-			return r.ReferenceName
-		}
-	}
-	return nil
-}
-
 type OperationType uint8
 
 const (
@@ -138,34 +183,3 @@ func NewOperationType(method string) OperationType {
 	}
 	return OperationTypeUnknown
 }
-
-type Resources map[string]*Resource
-
-// ServiceHasValidResources returns true when resources are found for the provided serviceName that have usable operations
-// defined (specifically any operations that do not require a response model, or that have a response model for any response)
-// TODO: maybe remove this, we are not using this as it's preferable to error out rather than skip over
-func (r Resources) ServiceHasValidResources(serviceName string) bool {
-	for _, resource := range r {
-		if resource.Category == "" {
-			// These are logged earlier in the pipeline
-			continue
-		}
-
-		for _, operation := range resource.Operations {
-			if operation.Type == OperationTypeList || operation.Type == OperationTypeRead {
-				// Determine whether to skip operation with missing response model
-				if operation.Type != OperationTypeDelete {
-					if responseModel := operation.Responses.FindModelName(); responseModel == nil {
-						if operation.ResourceId == nil || len(operation.ResourceId.Segments) == 0 || operation.ResourceId.Segments[len(operation.ResourceId.Segments)-1].Value != "$ref" {
-							continue
-						}
-					}
-				}
-			}
-
-			return true
-		}
-	}
-
-	return false
-}