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.
Related
Basic authentication is working fine in my openapi v3 document running in swagger-ui. Now I want to add Google+ oauth2 authentication. Can you point me to good newbie documentation how to do this?
I find the configuration options a bit overwhelming as I don't know what options to choose. Most examples I find using a google search seem to be swagger v2 based or result in me thinking I'm an idiot (which may be the case, but I think it has more to do with knowing little about google oauth flows).
The OpenAPI Specification supports the description of OpenID Connect authorization, however Swagger-UI and Editor have not yet implemented it.
The lack of this functionality has been added to the GitHub swagger/swagger-ui issues #3641 list of features not yet supported by Swagger-UI.
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
When working with dart, you stumble upon a few generated libraries. There is a whole GitHub group with a collections of those: https://github.com/dart-google-apis
I have not yet figured out how these libraries are generated? Are they compiled from another language? Which language? And which compiler is used?
Most of Google's external APIs are described in JSON document by an API called the Discovery Service. The document is called the discovery document and provides enough information to generate a client API that can represent the APIs resources as objects and can connect over HTTP to make calls. The Dart libraries you linked to were generated this way.
You can read about the Discovery Service here: https://developers.google.com/discovery/v1/using
And the generator that those libraries used is here: https://github.com/dart-gde/discovery_api_dart_client_generator
Is there any reason why the default plug and play F# type providers to web services is soap based wsdl? Is it because of a lack of formal contracts in REST? Such that each REST api may differ significantly and hence making a general REST provider difficult to provide?
Type providers need machine-readable type schema to do their jobs well.
Type providers need schema. So you could use Open Data Protocol that is REST + schema. For that task you could use ODataTypeProvider that is already implemented.
I think that this is because there is no way to know how the API looks. Humans can read the documentation, but the Type Provider cannot. Other APIs have XML specifications, so they are easier.