Merging of restrictions annotations on entity sets and navigation property paths

[HeikoTheissen]

Example: In tools/tests/annotations.xml, the resource path /ReadOnlySingleton/ReadOnlyMany is bound to the entity set TwoReadOnlySet

odata-openapi/tools/tests/annotations.xml

Line 262 in 0b4afb4

<NavigationPropertyBinding Path="ReadOnlyMany" Target="TwoReadOnlySet" />

which has ReadRestrictions

odata-openapi/tools/tests/annotations.xml

Lines 495 to 500 in 0b4afb4

	<Annotation Term="Capabilities.ReadRestrictions">
	<Record>
	<PropertyValue Property="Description" String="Supports read-list" />
	<PropertyValue Property="LongDescription" String="Does not support any query options" />
	</Record>
	</Annotation>

But the "get summary" for this resource path is not taken from these ReadRestrictions but rather from the fallback-summary of the template operation-summary-description.

odata-openapi/tools/V4-CSDL-to-OpenAPI.xsl

Lines 3167 to 3169 in 0b4afb4

	<xsl:call-template name="operation-summary-description">
	<xsl:with-param name="restriction" select="$readRestrictions" />
	<xsl:with-param name="fallback-summary">

The output is

odata-openapi/tools/tests/annotations.openapi3.json

Lines 1977 to 1979 in 0b4afb4

	"/ReadOnlySingleton/ReadOnlyMany": {
	"get": {
	"summary": "Get entities from related ReadOnlyMany",

and not

"/ReadOnlySingleton/ReadOnlyMany": { 
     "get": { 
         "summary": "Supports read-list",
         "description": "Does not support any query options",

General observation: Depending on the resource path, restrictions for operation-summary-description are only taken from the annotations

• Capabilities.…Restrictions if the resource path is an entity set
• Capabilities.NavigationRestrictions/RestrictedProperties/…Restrictions if the resource path contains a navigation property.

In the second case, other templates also consider Capabilities.…Restrictions of the bound entity set if there are no Capabilities.NavigationRestrictions/RestrictedProperties/…Restrictions for the navigation property. Why is the operation-summary-description template different?

[mikepizzo]

Question is: is it more meaningful to give a generic description of the relationship than to default to the description on the bound entity set.

[HeikoTheissen]

OData-OpenAPI-v1.0 does not mention where the summary in a member of paths should come from. It gives only examples.

I prefer service-specific texts over generic texts, hence expect the following order:

1. Service-specific Core.Description in navigation-path-specific Capabilities.NavigationRestrictions/RestrictedProperties/ReadRestrictions
2. Service-specific Core.Description in entity-set-specific Capabilities.ReadRestrictions
3. Generic summary "Get entities from related ..."

In the example # 2 exists but # 1 does not, I expect # 2 to be the summary.

But the current implementation considers only # 1 and # 3, hence # 3 is the summary.

[mikepizzo]

Assuming nav prop "customers" on a product:

"/Products/{Id}/Customers": {
"get": {
"summary": <...>,
"tags": [
"Products"
],

Order of preference:

1. Read Restrictions for path
2. Read Restrictions of entity set <=currently omitted
3. Generated "Get entities from related "

We don't currently look at description of entity set/nav prop because we want to differentiate between read/write