Why We Use Swagger For API Documentation | Dreamfactory

Nothing makes a REST API easier to use than good documentation. Well, nothing except maybe a live test environment right there in the API documentation. And help with generating client side code to use your API would be awesome too. Come to think of it, having the documentation and test environment dynamic enough to update as you on-board more services would be a major plus. Well, you get all that and more with the latest DreamFactory DSP REST API with Swagger.

What is Swagger? 

Because REST APIs are not auto-discoverable, it was historically difficult if not impossible for fellow developers to understand API behavior (endpoints, input parameters, output values, etc) barring the availability of custom documentation or access to the API source code. This all changed with the advent of Swagger. Provided with a JSON/YAML specification defining your API structure, Swagger can create interactive API documentation, generate client libraries in many different programming languages, and more.

Why We Use Swagger

We wanted our REST API, and that of any added web services, to be easy to understand, quick to test, and simple to use right out of the box. The Swagger framework solves our server, client, documentation and testing sandbox needs, all in a language-agnostic specification, with plenty of open-sourced server and client side resources already available to help with generation. It also comes with an open-sourced front end, the Swagger UI framework, which quickly allows developers to work with the API, giving them a clear picture of how the API responds to requests with various parameters and options. It helps us to provide what a developer needs to get an app up and running with powerful web services with little time and effort.

The interactive documentation is incredibly useful, as developers are provided with a web interface which allows for easy experimentation with the underlying API. The following example depicts DreamFactory's Swagger UI integration for a MySQL API. The user can set one or more of the many API parameters available for this particular endpoint (retrieve records from a table), identify the table name, and when the Execute button is pressed, the response will be output in JSON format.

How DreamFactory Generates API Documentation with Swagger

Documenting static services of our API is as easy as annotating server-side code, just as you would use javadoc or phpdoc. You define the API services, including path variables, query parameters, and even members of the posted body data, along with models of any data types passed between client and server. Documentation is then easily generated in various formats (json, xml, etc) and cached for speedy access from clients.

We then generate client-side code from the resulting documentation for our API. We use this generated code in our apps, as well as, presenting them as SDK jump-starters for app developers using our platform.

At DreamFactory, we added a little twist by allowing web services to be added or removed dynamically. For any non-native service that is added to your platform's API, a json or xml Swagger document meeting the specification can be added and/or modified to define that service, immediately making it testable from the included Swagger UI framework and usable by client-side generated code.

Using Swagger Documentation with DreamFactory

The easiest way to learn more about how DreamFactory's Swagger integration works is by spinning up a free (no credit card required) 14 day trial at https://genie.dreamfactory.com/register. Alternatively, you can download a free on-premise version of the platform via the DreamFactory website. If you'd like to trial a commercial version of the platform, or just have questions, schedule a quick call with our team!