The Watson API documentation Swagger document returns NOTHING!

watson-developer-cloud / api-guidelines

:cop: REST API guidelines created for the Watson Developer Cloud services

http://www.ibm.com/smarterplanet/us/en/ibmwatson/developercloud/

Apache License 2.0

137 stars 36 forks source link

The Watson API documentation Swagger document returns NOTHING! #2

Closed danifitz closed 8 years ago

danifitz commented 8 years ago

I'm at a customer event and I've just demo'd the amazing value of Watson and Bluemix. Now I'm trying to show developers how to use the services and API documentation is broken. https://www.ibm.com/smarterplanet/us/en/ibmwatson/developercloud/apis/listings/api-docs.json

The JSON document is empty. This is so frustrating I could cry. Please fix this as soon as possible, i have a few hours at this event to save face.

chughts commented 8 years ago

Daniel,

For the API documentation always start here https://www.ibm.com/smarterplanet/us/en/ibmwatson/developercloud/

Then drill down into a service, then into the documentation then into the API specs. Eg for concept Insights https://www.ibm.com/smarterplanet/us/en/ibmwatson/developercloud/concept-insights/api/v2/

danifitz commented 8 years ago

@chughts unless the link has been fixed I don't think this issue can be closed. This is the main route to view documentation for the Watson API's. It took me over 30 mins to find the alternative documentation that you posted in your response. While the documentation you have sent me is indeed useful, the original issue remains that the official docs are broken.

SirSpidey commented 8 years ago

@danifitz, Daniel, sorry that the API docs link is incomplete. We will get that fixed.

In the meantime, as @chughts mentioned, you can see complete API documentation by starting with the service. Services have a link to the complete API reference (with examples in several languages). That API reference includes a link to a dynamic API explorer (swagger).

For example, for the Natural Language Classifier:

Docs page: http://www.ibm.com/smarterplanet/us/en/ibmwatson/developercloud/doc/nl-classifier/
Link in left navigation pane to API reference: http://www.ibm.com/smarterplanet/us/en/ibmwatson/developercloud/natural-language-classifier/api/v1/
Link in API reference to API explorer: https://watson-api-explorer.mybluemix.net/apis/natural-language-classifier-v1

nfriedly commented 8 years ago

BTW, there's a redirects section in docpad.coffee in the developer-cloud repo on GHE. Add an entry in there and then it should automatically redirect the old URL to the new one.