Are there any significant differences between Swagger and OpenAPI?
What is better to use in conjunction with Python (Django)?
As I understand it in general, Swagger is a commercial product, and OpenAPI is an open-source.
OpenAPI is the specification. Meanwhile Swagger is tools to implement the specification. Originally the specification was Swagger specification but it was donated to become a standard with more companies behind.
See What Is the Difference Between Swagger and OpenAPI?
Related
Quick and simple: Is it possible to get the complete OAS/YAML/JSON definition of these APIs? For example the ESIGN API.
I want import these definitions and generate a connector to do a low/zero coding implementation.
Thanks in advance.
AA
Alejandro, you're in luck.
DocuSign uses the OpenAPI (OAI) Specification - formerly known as "Swagger" - to describe its REST APIs. The goal of the OAI specification is to define a standard, language-agnostic interface to REST APIs which allows both humans and computers to discover and understand the capabilities of the service. For more info see the official OAI spec.
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!
How do we document a message based API in Swagger or RAML ?
By message based I mean that the endpoint is always the same, but one can send multiple message types to this endpoint and depending on the type of input message we get different responses.
Is there an example of this type of API I can have look ?
Thank you.
Luis Oscar
Swagger and OAS is especially used to document REST-like APIs. After a long search I have found the AsyncAPI specification. This can be used to document your message driven APIs.
There´s also an online editor available and if you are already familiar with using swagger, yaml it is easy to get started with this specification
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.
Has anyone configured swagger with spring-data-rest. I know swagger has DocumentationConfig class which scans for all spring-mvc request mappings. But, how to use that for spring-data-rest as there are no explicit request mappings defined. Any help in this regard is greatly appreciated. Also, like to know, if there are any other documentation framework which supports Spring-Data-Rest.
In version greater than 2.6.0 of SpringFox, support for spring data rest was added (but it's still in incubation). In order to add support for Spring Data Rest, you need to include the dependency below:
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-data-rest</artifactId>
<version>2.6.1</version>
</dependency>
This has been lingering out there a while, but as others have mentioned, there are (still) no Swagger implementations that support Spring Data Rest. However, Spring Data Rest does follow the HAL specification, and the HAL Browser integrated really seamlessly with any SDR project. Coupled together with the newer versions of SDR that expose ALPS metadata, this should be very sufficient for your documentation goals.
Answer for your second question:
AsciiDoctor combined with Spring REST Docs/RestAssured can be neat way of documenting SDR endpoints. It does require a bit of manual effort though, as the only automated part will be the creation of snippets. These can then be loaded into your AsciiDoc files.