Support for OpenAPI description in a Infragistics AppBuilder integration use case

[chrohrbach]

What happened?

It seems that DAB does not generate enough information when an endpoint is called by Infragistics AppBuilder that requires some details to be able to use the endpoint correctly, see the description here. I searched for possibilities to configure the expressivness of DABs openapi interface but did not find any information about such a possibility. In a Infragistics forum post, see here, the problem is described and solved with access to the underlying endpoint source code, i don't feel confident to go to the source code of DAB to check this. Thanks for your time in helping me out with this topic.

Version

latest

What database are you using?

Azure SQL

What hosting model are you using?

Local (including CLI)

Which API approach are you accessing DAB through?

REST

Relevant log output

No response

Code of Conduct

• I agree to follow this project's Code of Conduct

[chrohrbach]

It has been determined that Infragistics AppBuilder is looking for a missing property in the schema, see below

It is unclear if this is required by the OpenAPI specs or if it is a miss interpretation by Infragistics.

[pmoleri]

Here's the code that creates the Schema with "properties" but no "type".

data-api-builder/src/Core/Services/OpenAPI/OpenApiDocumentor.cs

Lines 938 to 941 in 466c18a

	Schema = new()
	{
	Properties = responseBodyProperties
	}

[pmoleri]

I think this needs to be considered as a bug.
The lack of the "type" permits any other type as valid:

The mere presence of "properties" is not enough to specify type object.

[chrohrbach]

Thanks make sense. How do we go forward from here ?

[seantleonard]

Thank you for reporting, @chrohrbach. I'm working on a fix.

I found a relevant thread that discusses whether type is a required property. Consensus is that type isn't required:

• Is type a required field for Schema Objects? OAI/OpenAPI-Specification#1657
  • OpenAPI-Specification discussion
• Getting a type error when using an OpenAPI spec with a header that's missing schema.type PaloAltoNetworks/docusaurus-openapi-docs#430
  • Example of how different tooling handles type or missing type differently.

Ultimately, different tooling handles the presence of the type property differently. Some may try to guess the type when not present:

• e.g. object when the property properties exists.

That said, there is no reason why DAB shouldn't add this so that Infragistics tooling can work. I'm curious whether this is the only error that Infragistics emits when evaluating the OpenAPI document generated by DAB.

[chrohrbach]

Thx for you work

[pmoleri]

Hi @seantleonard ,

Thank you for picking up this. While it's true that type is not required, I think it's incorrect in the context of DAB response.

• type + properties means "it must be an object and the properties are as described
• properties only means "it can be any type, when it's an object the properties are as described
  (see my validation example with a plain integer in the previous post).

DAB response is always an object and it's best described as such as it will improve compatibility.
I'm glad you agreed, I just wanted to provide additional input for the decision.
Thanks again

[seantleonard]

Hi @seantleonard ,

Thank you for picking up this. While it's true that type is not required, I think it's incorrect in the context of DAB response.

• type + properties means "it must be an object and the properties are as described
• properties only means "it can be any type, when it's an object the properties are as described
  (see my validation example with a plain integer in the previous post).

DAB response is always an object and it's best described as such as it will improve compatibility. I'm glad you agreed, I just wanted to provide additional input for the decision. Thanks again

Sorry to imply that I was trying to justify whether to do this or not. I fully intend to do so.

I intended to figure out whether type was required because I wanted to identify why https://github.com/microsoft/OpenAPI.NET didn't complain about missing type. An error if type were required would have helped prevent this becoming an issue in the first place. Thanks for bringing this to my attention.

[JerryNixon]

Related #2262