support odata?

[fehguy]

There are many parts of oData that can be supported by swagger easily. Worth investigating if the nuances are added to the future spec.

[webron]

We definitely need more input here. @allan-d-c, @mkrouwer, @arnos - can any of you pitch in?

[phil-scott-78]

love to see at least some of the querying support. $top, $skip, $orderby would be a big start

[martys]

That would be very helpful - in terms of allowing users to "try out" the api.
Default Odata doc's work fine for Get`ing data, but lacks on Query building, or especially posting and providing samples for the users

[webron]

I wonder if this is still relevant now.

[martys]

Why would it NOT ?
Swagger is a very usefull tool for "discovering" the API, and avoiding the need of special 'chrome' plugins to do the testing

Also for support calls for the APi, when a user send a request sample that doesn't work

i can keep on going...

My point is - it's a webAPI, so what that it has this odata rule set on top of it ?
Users of the API still need doc's, still need samples, and still need a place to 'test'

[fehguy]

Yes, i think we should keep this discussion going.

[martys]

Well - here's an example that we were able to put together with some work-arounds http://bit.ly/1CUfOsO

kinda works for discovery.

Had problems with setting up the available content types,
also had to re-write the paths manually.. (it tried to put api/xxx instead of odata/xxx)

still need to 'expose' custom and transient actions somehow

need to provide samples (the default one's don't work with odata, cause referenced properties must be specified as Links, but not embeded as a sub-resource)

still need to find a way to 'document' $batch operation' support

[webron]

@martys - just to explain, my comment was a misunderstood joke (referring to something that was published outside this forum). I didn't mean to imply it's not really relevant anymore.

And thanks for adding your input, every little bit helps.

[prashanthpatha]

We are using Apache olingo implementation for OData project and we want to expose the API docs using swagger. With annotations approach of swagger, swagger is depending on the rest API related annotations like @path for paths and swagger is implemented for the Rest API's even. But OData implementation source would not have annotations like @path and API is different from pure Rest API. Then how can we use swagger with annotations in code for generating docs ? Is it our only choice to write manual json files for exposing docs here ? How we can use swagger for OData implementation ?

[webron]

@prashanthpatha - can't say I'm familiar with olingo. If it doesn't use JAX-RS annotations, or basic servlets, you can't use swagger-core with it as-is. I imagine it's possible to write a Reader for it, but don't know anything about that project to say how easy it is.

[arnos]

@prashanthpatha out of curiosity are use using OLingo v2 or v4?

If it's v4 we could also ask the Olingo guys if they want to pitch in
support (they are already doing the reference javascript implementation as
well)

On Fri, Apr 24, 2015 at 10:29 AM, Ron notifications@github.com wrote:

@prashanthpatha https://github.com/prashanthpatha - can't say I'm
familiar with olingo. If it doesn't use JAX-RS annotations, or basic
servlets, you can't use swagger-core with it as-is. I imagine it's possible
to write a Reader for it, but don't know anything about that project to say
how easy it is.

—
Reply to this email directly or view it on GitHub
#230 (comment)
.

[Ajay102]

Hi @martys , Could you please let me know what are the workarounds you have made to make Swagger ON on Odata endpoint.

[Ghkuijer]

Hi @martys , I have the same question as @Ajay102 . Can you maybe post some code on which work arounds did the trick. Many people are searching for ways to document an OData API, and we are too. The example looks great!

[ralfhandl]

Hi,

I'm a member of the OASIS OData Technical Committee and currently working on a metadata format for OData services based on JSON Schema. I'm also investigating how to use Swagger for describing OData services, and being a fan of the DRY principle I'd like to do it this way:

• have a JSON Schema document with extensions that describes the structural elements of an OData service
• have a separate Swagger document that describes the top-level resources and references the JSON Schema document for the payload formats

Unfortunately this does not work because

• Swagger only uses a subset of JSON Schema Draft 04, especially no anyOf and no type arrays
• Swagger restricts the JSON Schema extensibility to x- keywords

Until these obstacles are removed we'd have to

• Repeat ourselves and clone large parts of the JSON Schema document in a stripped-down version into the Swagger document
• Lie to Swagger clients and don't tell them that a string property may sometimes return JSON null, or a numeric property may sometimes return the strings "NaN", "INF", or "-INF"

Any ideas on how to work around these obstacles are highly welcome!

Thanks in advance!
--Ralf

[OzBob]

@ralfhandl @martys OData/ODataSamples#13 supposedly there is an internal ODATA team tool that generates Swagger for odata WebApi's ....

[joshbooker]

Swashbuckle can do swagger for ASP.net WebAPI OData by using this nuget
https://github.com/rbeauchamp/Swashbuckle.OData
Sample here:
http://swashbuckleodata.azurewebsites.net/swagger/ui/index

[LasneF]

@webron should this ticket beeing closed ?

to me Odata has followed it s own pattern / way that would be quite difficult to map in OAS , especially all the dynamicity.
OData contains a definitive query language in a way similar to what graphQL can be (only in a certain way)

https://docs.oasis-open.org/odata/odata-json-format/v4.0/odata-json-format-v4.0.html

there is a video here about OAS & OData
https://learn.microsoft.com/en-us/shows/on-net/adding-a-little-swagger-to-odata#time=05m17s

but still i do not see too munch what should be for OAS taskforce here ...

[ralfhandl]

I’m in favor of closing this issue.

Main problems when defining an OData to OpenAPI Mapping were

1. Nullable properties
2. Primitive type system
3. High degree of repetition
4. Inability to express OData URL syntax

No. 1 has been improved from OpenAPI 2.0 to 3.0 and is now solved with OpenAPI 3.1.

No. 2 has been solved with the Formats registry.

No. 3 may be improved in Moonwalk with Context property annotations, until then we live with the fact that the generated OpenAPI documents can easily have ten times the size of OData's native API descriptions.

No. 4 is acceptable, OData-specific query options are described as type: string and link to the OData syntax definition in their description like in this example.

[handrews]

Thanks, @ralfhandl - this sounds like it's worth closing. Anyone wanting to address No. 4 in more detail should follow #1502 which would provide a way to do that.