extension-128.pngWhat is Swagger (a.k.a. The Open API Initiative)

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 TileSimple Stream w/External Object Support

screenshot-1.png?raw=true

  • Creates a link on the navigation bar (Apps > Swagger for Jive) to view a (non-place) Swagger specification.
  • Pass it Gadget URL Parameters to render a different Swagger specification URL.
  • For practical uses, this experience will most likely change to a list of API specifications to navigate to and view.

screenshot-2.png?raw=true

  • Embed a Swagger UI specification into a Custom View Tile located on a Tile Page. 
  • Configure the Swagger specification URL via the Tile Configuration experience.
  • Decorate your documentation page with additional information using other Tiles to customize the experience.

screenshot-3.png?raw=true

  • Using a Simple Stream Tile, create activity in a Jive place with a simple HTTP POST with meta-data that points to specific Swagger specification file(s).
    • Great for automated build integrations into Jive
  • Can push in either a Swagger specification URL or the entire Swagger specification JSON.

Other Use-Cases

  • Place "App" Tab - Configure a Place (Manage > Settings > Configure) to map to a specific Swagger specification which will be presented in a "Documentation" tab on the Place.
    • This option creates a place-specific URL that is "bookmarkable" to navigate straight to the documentation (includes Gadget URL Parameter overrides)
    • If not defined, the tab will not appear. 

 

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!

 

Another idea I was kicking around was to port the add-on to support different themes, or in some cases, new layouts to resemble TripIt's Slate interface!

 

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!