Skip navigation

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!

 

The Developer Days are Coming!

 

You guys have been asking for it, and we've listened! Taking your feedback from JiveWorld16, we're going take our hackathon materials on the road in a 4 hour workshop + hack day event to a few major cities around the nation. So be sure to bookmark this page and stay up to date on events! Below are some answers to questions you might have until we do our official announcement.

 

Official announcements with final details coming soon!

 

What is it?

It's a hour-long workshop for creating middleware-less add-ons for Jive, then a ~4 hour hack sessions where you work together in a team on an idea YOU come up with, based on given criteria or use some of the pre-defined examples.

 

Why are you doing it?

Because an overwhelming number of Developers asked, and we thought it was a great idea, and we love great ideas just as much as we love watching people come up with really cool solutions to real world problems & use-cases using Jive. At the end of the day, we want you to not only know how powerful Jive is, we want you to know how to harness the power yourselves.

 

Who is going to be there?

If you're reading this, then hopefully YOU! We want every developer to go to this very developer-centric event to get trained and learn more in depth about how you can do more for your community with hands-on coverage of middleware-less solutions. Both myself and Ryan Rutan will be at each of these events to help steer you in the right path and show best practices

 

How much is it going to cost me to attend an event?

All you need to bring is curiosity. The events are free, you'll just need to register (to be announced, TBA).

 

When and where are the events?

Good question! We're working all of that out, but until we do, we'd love to hear in the comments below of where you'd like us to go and how may people from your team you think would be interested.

Filter Blog

By date: By tag: