Include OData navigational properties in Swagger API documentation

[sebekz]

Let's say I have the following action method on my ODataController

public IHttpActionResult GetTrophiesForGame(long key)

This is an implementation of a OData navigational property with the URI like /api/Games({id})/Trophies

When I generate my Swagger API documentation, such navigational properties are nowhere to be seen. How can I point out in my API documentation, that a particular navigational property has been implemented and is supported in my API?

[VisualBean]

I dont think you can, except for the summary xml tag

[VisualBean]

And the remark tag

[sebekz]

Thanks @VisualBean. Is it a Swagger or Swashbuckle limitation? Perhaps I could try to implement it and post a PR if someone pointed me in the right direction.

The summary and remarks xml tags that you mentioned - I have these on both the controller class and individual action methods, and the only one that is picked up by Swagger is the summary one on the action method, the other ones are not included in the API doc generated by Swagger. Perhaps I am doing something wrong, could be, I am new to Swashbuckle.

[domaindrivendev]

Have you looked at Swashbuckle.OData? Vanilla SB doesn't really support OData very well. But this OData extension seems to do a pretty good job and I see navigation properties mentioned in their docs.

[sebekz]

Yes I did. Without it it's pretty much useless with OData. Unfortunately, navigational properties can only be enabled in entity swagger model previews, but not in case implemented navigational endpoints

[SiberaIndustries]

Without the possibility to include the navigational properties of OData EDM, a swagger doc is mostly useless for developers who needs an idea about the current api contracts.

So as @sebekz mentioned already, the question of what the limitations of Swashbuckle are must be answered first. I will invest some time for this issue because it is a realy important and helpful enhancement. I am very appreciative if someone already has an idea.

[freeranger]

Hi,

We created a dictionary of NonBodyParameter objects, one per AllowedQueryOptions value.

Then we created an OperationFilter that took an ODataValidationSettings and filtered the list for the allowed values and added them to any operation that had an ODataQueryOptions parameter.

We configured ODataValidationSettings globally for the application and added it to the ServicesCollection so it could be injected into the filter.

hth