Swagger is a growing REST API documentation standard that comprises multi-stages of the software development life-cycle. The standard is designed to allow architects, developers and business users to collaborate at early stages about capabilities of the API, while enabling developers to continue that momentum into the software developer stages with tools like auto code and documentation generation.
For more details about Swagger, you can check out the following links: http://swagger.io/
Why Swagger for Jive
When you look at what Swagger is trying to accomplish with bringing teams together, enabling faster productivity and creating awesome user experiences with documentation ... there seemed to be a natural alignment with what Jive does best. This observations was supported by conversation at JiveWorld16, (see: JiveWorld16 Developer Conference ... It's a Wrap!), where there was a lot of expressed interest about Jive, developer documentation and specifically Swagger. I must have talked to at-least 10 developers about this very use-case, and as a result of these conversations...a lot of really cool ideas bubbled to the surface. In standard Ryan fashion, I started to tinker. Tinkering led to coding, deploying and then testing. Before I knew it, I was putting the final touches on an early version of an add-on I like to call, Swagger for Jive!
What Does It Do
In general, the current version of Swagger for Jive add-on makes it such that the Swagger UI view of a given Swagger specification file can be viewed in-context in a Jive community.
One of the biggest requires for this solution that I wanted to impose, was that it had to NOT require middleware! This was to make it easier for developers to give it a try!
Some of those experiences are listed below:
|Canvas View (Apps Menu > Swagger for Jive)||Custom View Tile||Simple Stream w/External Object Support|
But That's Not All
Embedding documentation in-context in Jive is just the first step, next up is building in the scaffolding to enable collaboration around the documentation, and to answer those scenarios, I'll share some ideas that I have in mind.
- Mouse-over a specific method, and ask a question to the linked community.
- Decorate methods in the documentation with indicators that show which are the most popular, or ones with the most questions.
- Easily embed links to specific methods into collaboration via a !app experience
- and much much more I am sure based on your feedback!
Using Swagger? Give It a Try!
Visit our Github repo and follow the instructions to give it a try. This is an open source effort, so the solution is not fully supported; however, Swagger has a vibrant community and the solution is a pretty straight forward app integration, so maintenance should not be that hard. Plus, all the source code is at your finger tips, and it's not that much. =)
Hope you enjoy, and looking forward to the feedback ... contributions and overall collaboration around this project!