What is the best way of documenting OData endpoints?
Is there a way to use Swashbuckle for it?
Yes, try Swashbuckle.OData. It adds Swashbuckle support for ODataControllers.
See it in action here: http://swashbuckleodata.azurewebsites.net/swagger
Yes, we are trying to support it like yaml -> Swagger, yaml -> csdl ..
But it will need time to implementation, you can see a prototype and track there https://github.com/OData/model-first
I actually got something working for this using the IDocumentFilter function within Swashbuckle. I answered a similar question on the GitHub repo for Swashbuckle. Check out my response here (it's either at bottom or toward bottom):
https://github.com/domaindrivendev/Swashbuckle/issues/149
I've posted an example of a working IDocumentFilter implementation that you could leverage to get your OData endpoint set up in the Swagger ui.
Asp NET and Asp NET Core Api Versioning
You can use Api Versioning (as it extends ApiExplorer with Odata information) for both WebApi and AspNetCore.
There are samples available for both:
WebApi
Asp Net Core
This sample how it integrates well with Swashbuckle/Swagger ui.
The easiest way to do that I found is to convert OData definition to Open API spec using https://github.com/oasis-tcs/odata-openapi
Then import the spec document into swagger is very easy.
Related
I want to showcase all my endpoints of an API Gateway in Swagger. For gateway, I have used Ocelot with Asp.Net Core 2.1 but Ocelot's documentation says it does not support Swagger. Anyhow, if anyone can give suggestion on this?
I have already investigated the approaches to achieve this. For now if you are not going to re-invent the wheel with custom your own implementations, then the MMLib.SwaggerForOcelot package is the option to go with. Please follow readme file provided by link above. It covers all aspects of using that package.
This is my understanding:
Swagger is a notation/rules to write documentation. But why is it called a framework (like Angular/MVC)?
Swashbuckle is a program (JavaScript?) that generates the documentation (based on Swagger rules).
Swagger UI displays the documentation. It uses Swashbuckle to do this.
Is this information correct? If not can someone explain in simple terms what Swagger, Swashbuckle, and Swashbuckle UI mean?
Also, what do I lose as an API developer if I do not use this?
Swagger is a notation/rules to write documentation. But why is it called a framework(Like angular/MVC)?
It is probably called a "framework" because its' purpose is to offer a systematic way of notating the interface of any RESTful service under the OpenAPI Specification. This is a big deal to developers because the spec is overseen by the Open API Initiative under the reputable Linux Foundation.
Swashbuckle is a program(javascript ?) that generates the documentation(based on Swagger rules)
Swashbuckle is more of a package (or a library) that you can make use of in your .NET Web API projects. It's purpose, as you have correctly indicated, is to generate the Swagger spec for your project. Additionally, the Swagger UI is contained within Swashbuckle so if you are developing an API in .NET it's really a nice one-stop shop of a package. It is almost entirely written in C#, not JavaScript.
Swagger UI displays the documentation. It uses Swashbuckle to do this.
Yes, it does display the Swagger spec in a nice, human-friendly manner. However, Swashbuckle is not a necessary component for this. They are, aside from what I just said previously, completely mutually-exclusive.
Also what do I lose as an API developer, if I do not use this.
This is now entering into the realm of opinion but I'll try to be objective about it. I use Swashbuckle to assist in the creation of clients for my application APIs. After getting past the implementation learning curve (which wasn't much), this package has saved me quite a bit of time of writing the clients myself. Writing a web client is a trivial thing for small applications but enterprise-level applications have a tendency to keep growing and/or changing in complexity so it is nice to have the creation/updating of these clients completely automated.
In short, if you decide not to use it you must either resort on an alternative method of API client generation or write/update the clients yourself. If you are only developing the back end this may be completely pointless to you but it would certainly help whoever is responsible for creating the client apps that will consume your API services.
I hope these answers have been helpful. Cheers!
Am pretty new to OData.
Per my internet reading what I've gathered is Apache Olingo is better (vs OData4j) for Java implementation of OData service and OData consumer.
Can you please help me with sample code of Olingo service and Olingo consumer?
Any help in this regard is much appreciated.
Have a good one.
Thanks.
First you'll want to consult Olingo's documentation here. Their documentation is alright for basics but once you start extending it there's not much out there. As you can tell from no one answering this for 18 hours OData doesn't seem to be a hot topic right now.
If you want to create a basic service without JPA this is a good resource: OData Service with Olingo
If you want to create an OData service that uses JPA this is a good resource: OData JPA Web App. Also this one is helpful Olingo OData with MySQL.
Here's a document on how to create a client: Olingo Client We actually use Excel as a client which is quite nice for Excel users. However, there are times when Excel has compatibility issues with certain features (EDM Complex Types). Here's some good documentation on how to use Excel and OData
I have a Web API using OData that I need to query. The client application is a SPA built with React/Redux, but it looks as if most data service libraries such as isomorphic-fetch do not support OData. Can BreezeJS be useful for me in this situation? Or OLingo's ODataJs? Any examples, tutorials, resources on using these or any other OData clients with Redux? AFAIK, I just need a the client library to query an OData source and support promises. And as far as the data I get back from the server, I just need simple json objects; no need for models that support binding.
I've seen discussions of Breeze + Angular/Backbone, but can it support Redux/React?
I doubt that either Breeze or ODataJS supports ES6, so if i had to wrap them in a ES6 module, would they still function properly?
Maybe it helps if you consider that OData isn't that far off from REST. If it's just about pulling the data from a OData service, you won't need much more than jQuery.getJSON and Breeze will work too. However, if you want to do it the fancy way, and want you app to introspect the meta-model and such, you should have a look at datajs or olingo.
Which namespace should I be using for the latest Microsoft Web API OData:
System.Web.Http.Odata or System.Web.Odata?
The same classes appear in both namespaces, but I have not found anything directly stating which one to use.
I did find this article where the code examples are using System.Web.OData:
http://www.asp.net/web-api/overview/odata-support-in-aspnet-web-api/odata-v4/create-an-odata-v4-endpoint
I just want to be sure.
There exist two namespaces and assemblies because the two versions of OData are incompatible, though they can be used side-by-side.
Use System.Web.Http.OData for OData v3 and use System.Web.OData for OData v4.
You can read more about this on this blog post: http://blogs.msdn.com/b/webdev/archive/2014/03/13/getting-started-with-asp-net-web-api-2-2-for-odata-v4-0.aspx
You can find samples for Web API OData v3 and OData v4 here: https://github.com/OData/ODataSamples/tree/master/WebApi