is there a path definition for metadata and service document?

[xuzhg]

Hi,

Does OData OpenAPI mapping doc define the rules for metadata and service document path?

Thanks,
-Sam

[ralfhandl]

Hi Sam,

No, it doesn’t. We assumed that only OData-aware clients would use the service document and metadata document, and these clients wouldn’t be interested in the OpenAPI document as it contains less information than $metadata.

Do you have situations where OpenAPI clients would be interested in the service or metadata document?

Thanks in advance
Ralf

[adriano-campanhola]

Hi @ralfhandl, in our use case, we publish the API's on Azure API Management, which will refuse any operation that is not currently defined on the interface. If we try to utilize any of the api's on a SAPUI5/UI5 frontend, those could require the $metadata operation, as the frontend could utilize it on startup.

[ralfhandl]

refuse any operation that is not currently defined on the interface

Well, then you've got a problem: the OpenAPI files are intentionally incomplete and only show the most prominent paths, they don't attempt to show all possible paths - given that OData's path syntax is recursive and based on the service's resource model, showing all possible paths is unreasonable.

The containment example shows a potentially endless recursion, and you can reach the contained folders only via their - potentially unlimited - chain of parent folders:

odata-openapi/examples/containment.xml

Lines 98 to 105 in 15220b9

	<EntityType Name="Folder">
	<Key>
	<PropertyRef Name="Name" />
	</Key>
	<Property Name="Name" Type="Edm.String" Nullable="false" />
	<Property Name="Description" Type="Edm.String" />
	<NavigationProperty Name="Folders" Type="Collection(self.Folder)" ContainsTarget="true" />
	</EntityType>

The generated OpenAPI file stops after five levels:

odata-openapi/examples/containment.openapi3.json

Line 4704 in 15220b9

"/Folders('{Name}')/Folders('{Name_1}')/Folders('{Name_2}')/Folders('{Name_3}')/Folders('{Name_4}')/Folders": {

Would Azure API Management allow to go deeper because paths for level 15 start with a documented prefix, or would it prevent accessing anything below level 5?

[adriano-campanhola]

Yep, it's a current a limitation from Azure API Management in general, but so far we haven't had to go deeper than a few levels.

[ralfhandl]

Recursion - API Management doesn't support definitions defined recursively (for example, schemas referring to themselves).

So this will be problematic:

odata-openapi/examples/containment.openapi3.json

Lines 4894 to 4910 in 15220b9

	"components": {
	"schemas": {
	"Containment.Folder": {
	"title": "Folder",
	"type": "object",
	"properties": {
	"Name": {
	"type": "string"
	},
	"Description": {
	"type": "string",
	"nullable": true
	},
	"Folders": {
	"type": "array",
	"items": {
	"$ref": "#/components/schemas/Containment.Folder"

Seems like you will have to design your services carefully to match the limitations of your API Management solution, and you'll have to tweak the OpenAPI files or fork this generator to suit its specific needs.