A live demonstration of Intellinote's Swagger-document-generating domain specific language.
Swagger is a popular, Apache-licensed framework for describing, generating and documenting REST-ful web services. Swagger was developed by Reverb (formerly Wordnik) for their Wordnik.com API.
Among its many components is Swagger UI, a "dependency-free collection of HTML, Javascript, and CSS assets that dynamically generate beautiful documentation from a Swagger-compliant API".
Both Swagger and Swagger UI rely on the Swagger Specification, a language-agnostic, JSON-based format for describing REST APIs (in a machine-readable format).
You can find a demonstration of the Swagger UI interface here, and an example of a Swagger Specification JSON document here.
Swagger-DSL is an MIT-licensed, a JavaScript/CoffeeScript-based, "domain-specific language" for generating Swagger Specification JSON documents. Swagger DSL was developed by Intellinote in order to streamline their own API documenation efforts.
While we love Swagger, the Swagger format seems to be primarly designed to be read by computer programs. Swagger documents are quite verbose, and can be difficult for humans to read, understand, write or maintain.
We developed Swagger DSL as a tool we could use to author and mantain documentation for our own REST-ful APIs. The goal of Swagger DSL is to provide a light-weight, extensible and most of all readable, format for creating Swagger Specification JSON documents by hand.
Intellinote is a multi-platform (web, mobile, and tablet) software application that helps businesses of all sizes capture, collaborate and complete work, quickly and easily.
Users can start with capturing any type of data into a note, turn it into a task, assign it to others, start a discussion around it, add a file and share – with colleagues, managers, team members, customers, suppliers, vendors and even classmates. Since all of this is done in the context of private and public workspaces, users retain end-to-end control, visibility and security.
Visit us at www.intellinote.net.