{"action":"created","issue":{"url":"https://api.github.com/repos/openwhisk/openwhisk/issues/597","repository_url":"https://api.github.com/repos/openwhisk/openwhisk","labels_url":"https://api.github.com/repos/openwhisk/openwhisk/issues/597/labels{/name}","comments_url":"https://api.github.com/repos/openwhisk/openwhisk/issues/597/comments","events_url":"https://api.github.com/repos/openwhisk/openwhisk/issues/597/events","html_url":"https://github.com/openwhisk/openwhisk/issues/597","id":159206656,"number":597,"title":"An API is only as good as its documentation (swagger)","user":{"login":"csantanapr","id":1094878,"avatar_url":"https://avatars.githubusercontent.com/u/1094878?v=3","gravatar_id":"","url":"https://api.github.com/users/csantanapr","html_url":"https://github.com/csantanapr","followers_url":"https://api.github.com/users/csantanapr/followers","following_url":"https://api.github.com/users/csantanapr/following{/other_user}","gists_url":"https://api.github.com/users/csantanapr/gists{/gist_id}","starred_url":"https://api.github.com/users/csantanapr/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/csantanapr/subscriptions","organizations_url":"https://api.github.com/users/csantanapr/orgs","repos_url":"https://api.github.com/users/csantanapr/repos","events_url":"https://api.github.com/users/csantanapr/events{/privacy}","received_events_url":"https://api.github.com/users/csantanapr/received_events","type":"User","site_admin":false},"labels":[{"url":"https://api.github.com/repos/openwhisk/openwhisk/labels/Epic","name":"Epic","color":"3E4B9E"},{"url":"https://api.github.com/repos/openwhisk/openwhisk/labels/swagger","name":"swagger","color":"bfd4f2"}],"state":"open","locked":false,"assignee":null,"milestone":null,"comments":1,"created_at":"2016-06-08T16:11:04Z","updated_at":"2016-06-08T16:30:29Z","closed_at":null,"body":"We are currently using swagger to document the OpenWhisk API.\r\n\r\nThe [whiskswagger.json](https://github.com/openwhisk/openwhisk/blob/master/core/controller/src/resources/whiskswagger.json) is not accurate matching the implementation of the OpenWhisk API.\r\n\r\nYou can view OpenWhisk API docs in [Swagger UI](http://petstore.swagger.io/?url=https://raw.githubusercontent.com/openwhisk/openwhisk/master/core/controller/src/resources/whiskswagger.json)\r\n\r\nThere are several issue reports of people finding this inconsistencies\r\n\r\nThis Epic is to capture all work items to get swagger docs stable and 100% accurate.\r\n\r\nWe currently have some tests here https://github.com/openwhisk/openwhisk/blob/9e87bbfc0e9326aa13ab233400b4b860fa97d34a/tests/src/system/rest/SwaggerTests.scala\r\n\r\nWe should reach a point that no PR is merged containing API changes if doesn't \r\naccompanied by swagger related changes.\r\n\r\nSomething for inspiration :-) https://rocketeer.be/blog/2015/03/api-quality/\r\n"},"comment":{"url":"https://api.github.com/repos/openwhisk/openwhisk/issues/comments/224647747","html_url":"https://github.com/openwhisk/openwhisk/issues/597#issuecomment-224647747","issue_url":"https://api.github.com/repos/openwhisk/openwhisk/issues/597","id":224647747,"user":{"login":"sjfink","id":1533170,"avatar_url":"https://avatars.githubusercontent.com/u/1533170?v=3","gravatar_id":"","url":"https://api.github.com/users/sjfink","html_url":"https://github.com/sjfink","followers_url":"https://api.github.com/users/sjfink/followers","following_url":"https://api.github.com/users/sjfink/following{/other_user}","gists_url":"https://api.github.com/users/sjfink/gists{/gist_id}","starred_url":"https://api.github.com/users/sjfink/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/sjfink/subscriptions","organizations_url":"https://api.github.com/users/sjfink/orgs","repos_url":"https://api.github.com/users/sjfink/repos","events_url":"https://api.github.com/users/sjfink/events{/privacy}","received_events_url":"https://api.github.com/users/sjfink/received_events","type":"User","site_admin":false},"created_at":"2016-06-08T16:30:29Z","updated_at":"2016-06-08T16:30:29Z","body":"We have a few regression tests that check that the swagger matches the behavior.   We probably need many more such tests."}}
{"actor":{"display_login":"sjfink"}}