{"action":"created","issue":{"url":"https://api.github.com/repos/GoogleCloudPlatform/kubernetes/issues/11253","labels_url":"https://api.github.com/repos/GoogleCloudPlatform/kubernetes/issues/11253/labels{/name}","comments_url":"https://api.github.com/repos/GoogleCloudPlatform/kubernetes/issues/11253/comments","events_url":"https://api.github.com/repos/GoogleCloudPlatform/kubernetes/issues/11253/events","html_url":"https://github.com/GoogleCloudPlatform/kubernetes/pull/11253","id":95027093,"number":11253,"title":"[WIP]: Add a command to generate docs for types defined in pkg/api/v*/types.go","user":{"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},"labels":[{"url":"https://api.github.com/repos/GoogleCloudPlatform/kubernetes/labels/cla:%20yes","name":"cla: yes","color":"bfe5bf"}],"state":"open","locked":false,"assignee":null,"milestone":null,"comments":20,"created_at":"2015-07-14T19:59:59Z","updated_at":"2015-07-15T19:23:27Z","closed_at":null,"pull_request":{"url":"https://api.github.com/repos/GoogleCloudPlatform/kubernetes/pulls/11253","html_url":"https://github.com/GoogleCloudPlatform/kubernetes/pull/11253","diff_url":"https://github.com/GoogleCloudPlatform/kubernetes/pull/11253.diff","patch_url":"https://github.com/GoogleCloudPlatform/kubernetes/pull/11253.patch"},"body":"Address #10966\r\n\r\nSome known issues:\r\n1. In swagger spec, fields that has type \"map\" are set to type \"any\", so the generated docs doesn't set the type of these fields correctly. There are 14 matches of \"map\" in v1/types.go\r\nBTW, swagger-ui also suffers from this problem.\r\n\r\n2. Because in swagger 2.0, the fields are represented by \"Properties\", which is a map, so the order fields are not preserved. Currently I just sort the fields alphabetically.\r\n\r\n3. Links in descriptions are not rendered to markeddown links\r\n\r\nTodo:\r\n1. We can adapt the WriteSwaggerDocFunc() to write the .md docs if #10933 gets merged\r\n\r\n@erictune @bgrant0607 @nikhiljindal "},"comment":{"url":"https://api.github.com/repos/GoogleCloudPlatform/kubernetes/issues/comments/121720151","html_url":"https://github.com/GoogleCloudPlatform/kubernetes/pull/11253#issuecomment-121720151","issue_url":"https://api.github.com/repos/GoogleCloudPlatform/kubernetes/issues/11253","id":121720151,"user":{"login":"bgrant0607","id":7725777,"avatar_url":"https://avatars.githubusercontent.com/u/7725777?v=3","gravatar_id":"","url":"https://api.github.com/users/bgrant0607","html_url":"https://github.com/bgrant0607","followers_url":"https://api.github.com/users/bgrant0607/followers","following_url":"https://api.github.com/users/bgrant0607/following{/other_user}","gists_url":"https://api.github.com/users/bgrant0607/gists{/gist_id}","starred_url":"https://api.github.com/users/bgrant0607/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/bgrant0607/subscriptions","organizations_url":"https://api.github.com/users/bgrant0607/orgs","repos_url":"https://api.github.com/users/bgrant0607/repos","events_url":"https://api.github.com/users/bgrant0607/events{/privacy}","received_events_url":"https://api.github.com/users/bgrant0607/received_events","type":"User","site_admin":false},"created_at":"2015-07-15T19:23:27Z","updated_at":"2015-07-15T19:23:27Z","body":"I agree that we should de-emphasize subobject names. They are visible in the Swagger, also. Putting all the models into one doc would help, as would formatting top-level objects to be more prominent and subobjects to be less so."}}