{"action":"created","issue":{"url":"https://api.github.com/repos/GoogleCloudPlatform/kubernetes/issues/10933","labels_url":"https://api.github.com/repos/GoogleCloudPlatform/kubernetes/issues/10933/labels{/name}","comments_url":"https://api.github.com/repos/GoogleCloudPlatform/kubernetes/issues/10933/comments","events_url":"https://api.github.com/repos/GoogleCloudPlatform/kubernetes/issues/10933/events","html_url":"https://github.com/GoogleCloudPlatform/kubernetes/pull/10933","id":93842482,"number":10933,"title":"WIP: Automatic Generation of Swagger Documentation in Types","user":{"login":"andronat","id":793408,"avatar_url":"https://avatars.githubusercontent.com/u/793408?v=3","gravatar_id":"","url":"https://api.github.com/users/andronat","html_url":"https://github.com/andronat","followers_url":"https://api.github.com/users/andronat/followers","following_url":"https://api.github.com/users/andronat/following{/other_user}","gists_url":"https://api.github.com/users/andronat/gists{/gist_id}","starred_url":"https://api.github.com/users/andronat/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/andronat/subscriptions","organizations_url":"https://api.github.com/users/andronat/orgs","repos_url":"https://api.github.com/users/andronat/repos","events_url":"https://api.github.com/users/andronat/events{/privacy}","received_events_url":"https://api.github.com/users/andronat/received_events","type":"User","site_admin":false},"labels":[{"url":"https://api.github.com/repos/GoogleCloudPlatform/kubernetes/labels/cla:%20yes","name":"cla: yes","color":"bfe5bf"}],"state":"open","locked":false,"assignee":{"login":"caesarxuchao","id":2823529,"avatar_url":"https://avatars.githubusercontent.com/u/2823529?v=3","gravatar_id":"","url":"https://api.github.com/users/caesarxuchao","html_url":"https://github.com/caesarxuchao","followers_url":"https://api.github.com/users/caesarxuchao/followers","following_url":"https://api.github.com/users/caesarxuchao/following{/other_user}","gists_url":"https://api.github.com/users/caesarxuchao/gists{/gist_id}","starred_url":"https://api.github.com/users/caesarxuchao/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/caesarxuchao/subscriptions","organizations_url":"https://api.github.com/users/caesarxuchao/orgs","repos_url":"https://api.github.com/users/caesarxuchao/repos","events_url":"https://api.github.com/users/caesarxuchao/events{/privacy}","received_events_url":"https://api.github.com/users/caesarxuchao/received_events","type":"User","site_admin":false},"milestone":null,"comments":36,"created_at":"2015-07-08T17:07:39Z","updated_at":"2015-07-25T02:48:15Z","closed_at":null,"pull_request":{"url":"https://api.github.com/repos/GoogleCloudPlatform/kubernetes/pulls/10933","html_url":"https://github.com/GoogleCloudPlatform/kubernetes/pull/10933","diff_url":"https://github.com/GoogleCloudPlatform/kubernetes/pull/10933.diff","patch_url":"https://github.com/GoogleCloudPlatform/kubernetes/pull/10933.patch"},"body":"This is a proposal on how we can handle and export our documentation from **api/*/types.go** to **Swagger API**. Refs #3060 \r\n\r\n#### The basic idea\r\n 1. Export a description for the structs themselves\r\n 2. We have a lot of interesting information as comments in api/types.go, api/v1/types.go, api/v1beta3/types.go that we might want to export in Swagger API.\r\n 3. We make sure that we don't want to maintain documentation in multiple places.\r\n\r\n#### Problems\r\nIdeally we would like `go-restful` to be able to parse our source files and export struct and fields comments in the Swagger API. Unfortunately this is not possible (or just very hard) as Swagger's JSON is builded dynamically on runtime and parsing the source files requires 1) having the files in the deployment environment 2) pass the file paths to `go-restful`.\r\n\r\nCurrently `go-restful` is able to export field descriptions of a struct by parsing struct tags (using the `description` tag) and lately, struct description is also supported through the `modelDescription` tag. The issue with this method is how can we maintain a source-reader-friendly documentation in our files and keep swagger-friendly tags up to date (these are 1 line long descriptions). \r\n\r\n#### Solution\r\nIn this PR: emicklei/go-restful#215 we suggest an alternative way of keeping struct documentation through special methods attached on structs.\r\n\r\nThis PR is about creating a generator that parses the documentation from the Type files (this is done by using `go/doc` and `go/ast`) and automatically generates the aforementioned special documentation methods for each struct.\r\n\r\n#### A smaller issue on TODOs and various other comments\r\nWe want this parser to ignore TODO lists and various other comments in our source code.\r\n\r\nThe suggested solution is:\r\n 1. Ignore one line TODO comments\r\n 2. Use `---` in a line and everything after it will be not placed in swagger descriptions\r\n\r\n## **STILL WORK IN PROGRESS**\r\n**TODO:**\r\n 1. ~~wait for emicklei/go-restful#215 to be merged~~\r\n 1. ~~ignore TODOs (and maybe also other information) -> Use `---` and ignore everything after it~~\r\n 2. ~~polish output (keep paragraphs, keep indentation, keep newline chars in indented lines)~~\r\n 3. ~~ignore `json\",inline\"` tags~~\r\n 5. ~~Add a comment here that thoroughly explains what this file is, what it's for, how it's generated, etc~~\r\n 6. ~~Generator should not print keys for empty documentation (empty values overwrite struct tags)~~\r\n 7. ~~Refactor verify-descriptions~~\r\n 8. ~~emicklei/go-restful#219 needs merging~~\r\n 8. ~~emicklei/go-restful#222 needs merging~~\r\n 8. ~~change QueryParameter description in api_installer.go~~\r\n 6. ~~Move all description tags into comments~~\r\n 10. **Depends on #11406**"},"comment":{"url":"https://api.github.com/repos/GoogleCloudPlatform/kubernetes/issues/comments/124791030","html_url":"https://github.com/GoogleCloudPlatform/kubernetes/pull/10933#issuecomment-124791030","issue_url":"https://api.github.com/repos/GoogleCloudPlatform/kubernetes/issues/10933","id":124791030,"user":{"login":"k8s-bot","id":12551979,"avatar_url":"https://avatars.githubusercontent.com/u/12551979?v=3","gravatar_id":"","url":"https://api.github.com/users/k8s-bot","html_url":"https://github.com/k8s-bot","followers_url":"https://api.github.com/users/k8s-bot/followers","following_url":"https://api.github.com/users/k8s-bot/following{/other_user}","gists_url":"https://api.github.com/users/k8s-bot/gists{/gist_id}","starred_url":"https://api.github.com/users/k8s-bot/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/k8s-bot/subscriptions","organizations_url":"https://api.github.com/users/k8s-bot/orgs","repos_url":"https://api.github.com/users/k8s-bot/repos","events_url":"https://api.github.com/users/k8s-bot/events{/privacy}","received_events_url":"https://api.github.com/users/k8s-bot/received_events","type":"User","site_admin":false},"created_at":"2015-07-25T02:48:14Z","updated_at":"2015-07-25T02:48:14Z","body":"GCE e2e build/test **passed** for commit cc5b2d02ed66955199577475574a958a6d8a54b3.\n* [Build Log](https://storage.cloud.google.com/kubernetes-jenkins/pr-logs/cc5b2d02ed66955199577475574a958a6d8a54b3/kubernetes-pull-build-test-e2e-gce/3507/build-log.txt)\n* [Test Artifacts](https://console.developers.google.com/storage/browser/kubernetes-jenkins/pr-logs/cc5b2d02ed66955199577475574a958a6d8a54b3/kubernetes-pull-build-test-e2e-gce/3507/_artifacts/)\n* [Internal Jenkins Results](http://goto.google.com/prkubekins/job/kubernetes-pull-build-test-e2e-gce//3507)\n"}}