Over nine months ago, when we started planning how to create a new set of Software Development Kits (SDKs) and reference documentation for the DocuSign Signature REST API, one of the engineering managers here at DocuSign proposed that we base the projects on the Swagger standard. After a thorough investigation, we decided to go “all in” on Swagger, and it’s been a great decision so far, with many benefits.
What’s Swagger? Now known as the Open API Initiative, the Swagger project is an open standard for “standardizing … how REST APIs are described.” In other words, the Swagger standard enables a REST API to be precisely described, and the description itself can be read and used by software tools.
API descriptions written as Swagger files can be understood and used by many different types of software applications because the Swagger files themselves are written in a standard computer data format called JSON.
This has many benefits:
- “SDK Generator” applications can read a Swagger file and then automatically generate an SDK for a particular target language. The result is the ability to quickly create an accurate SDK for the API. The C#, Java, PHP, Objective-C, and Node.JS SDKs for the Signature REST API are now automatically generated from our Swagger file.
- Documentation applications can read a Swagger file and then automatically produce documentation for the API. The tight connection between the Swagger file and the reference documentation eliminates many sources of error in technical documentation. The new reference manual for the DocuSign Signature REST API is automatically generated from our Swagger file.
- The Swagger file can be used to automatically generate an “API Explorer” that enables users to easily try out the different methods in the API. The new DocuSign API Explorer is also automatically generated from the Swagger file.
- The creation of a large and ever-growing set of community and commercial tools that work with Swagger API descriptions.
The DocuSign Signature REST API Swagger File
There are different techniques for creating a Swagger file, and many are hand-written. We chose a less common, and more sophisticated approach for the DocuSign Signature REST API Swagger file: the API’s implementation itself was extended to generate the Swagger file. This technique is also called “reflection” – the software not only implements the API for its clients, it can also tell a client about itself.
The result is tight coupling between what the API does and the description of what it does. In other words, more accurate documentation for you and our other developers.
100% of the DocuSign Signature REST API reference documentation is included in its Swagger file. It’s over 12 Megabytes long!
This post has been a brief introduction to Swagger. We plan additional blog posts that will discuss our use of Swagger in more depth. If you have any comments, questions, or even blog topics you wish we would write about, please send us a note at [email protected].