{ DreamFactory: 'Blog' }

Why We Like Swagger for API Docs

Posted by Lee Hicks

Tue, Jun 4, 2013

LeeHicksNothing makes a REST API easier to use than good documentation. Well, nothing except maybe a live test environment right there in the 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.

Portable network graphics

Why 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.

How does DreamFactory use 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. 

Want to see our REST API in action using Swagger?

Try it here. Or create your own free DreamFactory Services Platform and develop until your hearts content.

Get started with DreamFactory with a free hosted DreamFactory development environment. Or, download and run it on the server, cloud, or desktop of your choice.

DreamFactory

Weekly Digest

Recent Posts