Swagger docs and supporting pages

[Alan Oehler]

Last year we released out REST APIs which had been designed using Swagger. But we wanted to be able to have additional material that were not easily wedge-able into the Swagger framework – at least not that I could see. I wanted to be able to have an API doc website that would include some overviews, and a couple of guides/tutorials on how to actually be able to use particularly complex APIs line our Stats API. At the time we decided to cook up something in house to "wrap" the Swagger-generated material; you can view it here:

https://apidocs.instartlogic.com

There's a home page that introduces the basics and links to the Swagger-generated pages and a couple of other static documents on how to actually use our property configuration and statistics reporting APIs, which require a lot of description.

I had to manage this manually for a time (too long) until we recently scripted it up, and can now build it and deploy it automatically. But it would be nice if could more tightly couple everything, and I wondered if it was possible to. I found this example, which is somewhat close to what I'd like to do:

https://watson-api-explorer.mybluemix.net/apis/concept-insights-v2

though the overview and descriptive material near the top is much less extensive than what I need to do. It also seems to have a wrapper home page similar to mine (though much simpler – merely a list of links on the left, which each opens a Swagger-generated page):

https://watson-api-explorer.mybluemix.net/apis/

Does anyone do this kind of thing entirely with Swagger? Is my basic approach a reasonable way to do this? (I'm currently working on moving the static site content to mkdocs to be able to get navigation generated automatically and to get search capability.)

Thanks!

[Alan Oehler]

Correction, that second Watson API link should be https://watson-api-explorer.mybluemix.net