[Feature] Adds support for RequiresExplicitBinding and ExplicitOperationBindings annotations for operations

[irvinesunday]

Fixes #323, #232

This PR:

• Uses the annotations Org.OData.Core.V1.RequiresExplicitBinding in operations and Org.OData.Core.V1.ExplicitOperationBindings in model elements to associate which operations are to be generated for which elements.
• Updates the unit and integration tests.
• Updates the release notes.

How it works

Take for example the operation:

<Action Name="getMemberObjects" IsBound="true">
  <Annotation Term="Org.OData.Core.V1.RequiresExplicitBinding"/>
  <Parameter Name="bindingParameter" Type="graph.directoryObject" Nullable="false" />
  <Parameter Name="securityEnabledOnly" Type="Edm.Boolean" />
  <ReturnType Type="Collection(Edm.String)" Nullable="false" Unicode="false" />
</Action>

The bindingParameter is of type graph.directoryObject. This means that all model elements of this type (including all of its derived types) will have the operation getMemberObjects appended to their paths. In order to restrict the generation of this operation only to certain instances of the binding type - directoryObject, we append the <Annotation Term="Org.OData.Core.V1.RequiresExplicitBinding"/> annotation to the operation (as shown above).

All the operations which bind to directoryObject, for example, may need to be annotated with this annotation to avoid generating irrelevant operations to all of its derived types..

The navigation property deletedItems is an instance of type Collection(graph.directoryObject):
<NavigationProperty Name="deletedItems" Type="Collection(graph.directoryObject)" ContainsTarget="true" />
Ordinarily it would have the path /directory/deletedItems/{directoryObject-id}/microsoft.graph.getMemberGroups which is invalid. The only valid operation for this navigation property path would be /directory/deletedItems/{directoryObject-id}/microsoft.graph.restore.

To restrict all the operations bound to instances of directoryObject from being generated as operations on the deletedItems navigation property and only allow the restore operation, we would create an ExplicitOperationBindings to the navigation property as such:

<NavigationProperty Name="deletedItems" Type="Collection(graph.directoryObject)" ContainsTarget="true">
  <Annotation Term="Org.OData.Core.V1.ExplicitOperationBindings">
    <Collection>
      <String>microsoft.graph.restore</String>
    </Collection>
  </Annotation>
</NavigationProperty>

The entity type directoryObject will need to invoke all the operations that are bound to it and since all the operations which bind to directoryObject have been annotated with the annotation Org.OData.Core.V1.RequiresExplicitBinding, a corresponding Org.OData.Core.V1.ExplicitOperationBindings annotations with the collection of allowable operations need to be specified. Specifying this annotation on the entity type itself would automatically propagate to all its derived types. Which is not what we want. Therefore, this corresponding annotation will need to be annotated on the navigation source instance of this entity type. For example:

<Annotations Target="microsoft.graph.GraphService/directoryObjects">
  <Annotation Term="Org.OData.Core.V1.ExplicitOperationBindings">
    <Collection>
      <String>microsoft.graph.checkMemberGroups</String>
      <String>microsoft.graph.checkMemberObjects</String>
      <String>microsoft.graph.getMemberGroups</String>
      <String>microsoft.graph.getMemberObjects</String>
    </Collection>
  </Annotation>
</Annotations>

The above will yield the paths:

/directoryObjects/{directoryObject-id}/microsoft.graph.checkMemberGroups
/directoryObjects/{directoryObject-id}/microsoft.graph.checkMemberObjects
/directoryObjects/{directoryObject-id}/microsoft.graph.getMemberGroups
/directoryObjects/{directoryObject-id}/microsoft.graph.getMemberObjects

Unless a corresponding derived type of directoryObject gets annotated with the Org.OData.Core.V1.ExplicitOperationBindings, these operations will not be created for paths of this derived type.

The net result from all this should be a significant reduction in the number of invalid operation paths and a reduction in the size of the OpenAPI document and consequently our SDKs. The appropriate annotations will need to be added to the CSDL through XSLT initially and later by workload teams to realise this.

NB: The default behaviour is preserved (all operations generated for the bound entity types) when none of these annotations are specified anywhere.

[andrueastman]

Thanks for this @irvinesunday

[sonarqubecloud]

Kudos, SonarCloud Quality Gate passed!   

0 Bugs
0 Vulnerabilities
0 Security Hotspots
4 Code Smells

94.8% Coverage
0.0% Duplication