{"action":"created","issue":{"url":"https://api.github.com/repos/kubernetes/kubernetes/issues/12677","labels_url":"https://api.github.com/repos/kubernetes/kubernetes/issues/12677/labels{/name}","comments_url":"https://api.github.com/repos/kubernetes/kubernetes/issues/12677/comments","events_url":"https://api.github.com/repos/kubernetes/kubernetes/issues/12677/events","html_url":"https://github.com/kubernetes/kubernetes/pull/12677","id":100840333,"number":12677,"title":"A new command to read types' description from Swagger - kubectl explain","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/kubernetes/kubernetes/labels/cla:%20yes","name":"cla: yes","color":"bfe5bf"},{"url":"https://api.github.com/repos/kubernetes/kubernetes/labels/component/kubectl","name":"component/kubectl","color":"0052cc"},{"url":"https://api.github.com/repos/kubernetes/kubernetes/labels/size/XL","name":"size/XL","color":"ee5500"}],"state":"open","locked":false,"assignee":{"login":"JanetKuo","id":4876867,"avatar_url":"https://avatars.githubusercontent.com/u/4876867?v=3","gravatar_id":"","url":"https://api.github.com/users/JanetKuo","html_url":"https://github.com/JanetKuo","followers_url":"https://api.github.com/users/JanetKuo/followers","following_url":"https://api.github.com/users/JanetKuo/following{/other_user}","gists_url":"https://api.github.com/users/JanetKuo/gists{/gist_id}","starred_url":"https://api.github.com/users/JanetKuo/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/JanetKuo/subscriptions","organizations_url":"https://api.github.com/users/JanetKuo/orgs","repos_url":"https://api.github.com/users/JanetKuo/repos","events_url":"https://api.github.com/users/JanetKuo/events{/privacy}","received_events_url":"https://api.github.com/users/JanetKuo/received_events","type":"User","site_admin":false},"milestone":null,"comments":63,"created_at":"2015-08-13T18:44:26Z","updated_at":"2015-09-25T20:35:12Z","closed_at":null,"pull_request":{"url":"https://api.github.com/repos/kubernetes/kubernetes/pulls/12677","html_url":"https://github.com/kubernetes/kubernetes/pull/12677","diff_url":"https://github.com/kubernetes/kubernetes/pull/12677.diff","patch_url":"https://github.com/kubernetes/kubernetes/pull/12677.patch"},"body":"This is a simple kubectl tool that parses the swagger schema and returns useful information for the various models/types we have.\r\n\r\nHere you can see an example output:\r\n```\r\n# kubectl doc model Pod\r\nMODEL: Pod\r\nPod is a collection of containers that can run on a host. This resource is created by clients and scheduled onto hosts.\r\n\r\nFIELD DESCRIPTIONS\r\n-> spec\t<PodSpec>\r\n     Specification of the desired behavior of the pod. More info:\r\n     http://releases.k8s.io/HEAD/docs/devel/api-conventions.md#spec-and-status\r\n\r\n-> status\t<PodStatus>\r\n     Most recently observed status of the pod. This data may not be up to date.\r\n     Populated by the system. Read-only. More info:\r\n     http://releases.k8s.io/HEAD/docs/devel/api-conventions.md#spec-and-status\r\n\r\n-> apiVersion\t<string>\r\n     APIVersion defines the version of the schema of an object. Servers should\r\n     convert recognized schemas to the latest internal value, and may reject\r\n     unrecognized values. More info:\r\n     http://releases.k8s.io/HEAD/docs/devel/api-conventions.md#resources\r\n\r\n-> kind\t<string>\r\n     A string value representing the REST resource this object represents.\r\n     Servers may infer this from the endpoint the client submits requests to.\r\n     Cannot be updated. In CamelCase. More info:\r\n     http://releases.k8s.io/HEAD/docs/devel/api-conventions.md#types-kinds\r\n\r\n-> metadata\t<ObjectMeta>\r\n     Standard object's metadata. More info:\r\n     http://releases.k8s.io/HEAD/docs/devel/api-conventions.md#metadata\r\n```\r\n\r\nand has this interface:\r\n```\r\n# kubectl help doc\r\nDocumentation of models and operations. API version in models can be defined as a prefix: v1.MODEL. For operations is embedded in the URL.\r\n\r\nUsage:\r\n  kubectl doc model MODEL-NAME | operation URL [GET|POST|PUT|DELETE|PATCH] [flags]\r\n\r\nExamples:\r\n# Get the documentation of the model and its fields\r\n$ kubectl doc model Pod\r\n\r\n# Get the documentation of a specific model that represents a field of an other\r\n$ kubectl doc model Pod.spec.containers\r\n\r\n# Search for models with similar name\r\nkubectl doc model -S Pod\r\n\r\n# Get all available operations (GET|POST...) of a URL. {name} can be an arbitrary string.\r\nkubectl doc operation /api/v1/namespaces/{name}\r\n\r\n# Get the documentation of the specific operation\r\nkubectl doc operation /api/v1/namespaces/{name} GET\r\n\r\n# Search for similar operations\r\nkubectl doc operation -S /api/v1/namespaces\r\n\r\nFlags:\r\n  -h, --help[=false]: help for doc\r\n  -S, --search[=false]: Search for similar models to given MODEL-NAME or URL\r\n```\r\n\r\nWe also support searching through the `-S` flag like this:\r\n```\r\n#kubectl doc model -S Pod\r\nPodSpec\r\nPodList\r\nPod\r\nPodCondition\r\nPodStatus\r\nPodTemplateList\r\nPodTemplateSpec\r\nPodTemplate\r\n```\r\n\r\nAn other feature we have is a \"dot\" notation on `Model.attribute.attribute` for further exploration of the API:\r\n```\r\n#kubectl doc Pod.status.conditions\r\nMODEL: PodCondition\r\nPodCondition contains details for the current condition of this pod.\r\n\r\nFIELD DESCRIPTIONS\r\n+--------+----------+--------------------------------------------------------------------------+\r\n| status | <string> | Status is the status of the condition.                                   |\r\n|        |          | Can be True, False, Unknown. More info:                                  |\r\n|        |          | http://releases.k8s.io/HEAD/docs/user-guide/pod-states.md#pod-conditions |\r\n+--------+----------+--------------------------------------------------------------------------+\r\n| type   | <string> | Type is the type of the condition. Currently only Ready. More info:      |\r\n|        |          | http://releases.k8s.io/HEAD/docs/user-guide/pod-states.md#pod-conditions |\r\n+--------+----------+--------------------------------------------------------------------------+\r\n```\r\n\r\n```\r\n#kubectl doc put /api/v1/namespaces/sdad\r\nSupported methods for: PUT /api/v1/namespaces/{name}\r\n\r\nParameters\r\n+-------+--------+--------------------------------+----------+--------------+---------+\r\n| TYPE  |  NAME  |          DESCRIPTION           | REQUIRED |    SCHEMA    | DEFAULT |\r\n+-------+--------+--------------------------------+----------+--------------+---------+\r\n| query | pretty | If 'true', then the output is  | false    | string       |         |\r\n|       |        | pretty printed.                |          |              |         |\r\n+-------+--------+--------------------------------+----------+--------------+---------+\r\n| body  | body   |                                | true     | v1.Namespace |         |\r\n+-------+--------+--------------------------------+----------+--------------+---------+\r\n| path  | name   | name of the Namespace          | true     | string       |         |\r\n+-------+--------+--------------------------------+----------+--------------+---------+\r\n\r\nResponses\r\n+-----------+-------------+--------------+\r\n| HTTP CODE | DESCRIPTION |    SCHEMA    |\r\n+-----------+-------------+--------------+\r\n|       200 | OK          | v1.Namespace |\r\n+-----------+-------------+--------------+\r\n\r\nConsumes\r\n  -> */*\r\n\r\nProduces\r\n  -> application/json\r\n```\r\n\r\n### IMPORTANT NOTE\r\nUntil #10933 is finished, the big gap under the MODEL title exists due to the absence of struct description.\r\n\r\n/cc @ghodss "},"comment":{"url":"https://api.github.com/repos/kubernetes/kubernetes/issues/comments/143347278","html_url":"https://github.com/kubernetes/kubernetes/pull/12677#issuecomment-143347278","issue_url":"https://api.github.com/repos/kubernetes/kubernetes/issues/12677","id":143347278,"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-09-25T20:35:12Z","updated_at":"2015-09-25T20:35:12Z","body":"Thanks for all the work on this. We can improve it more later. Please rebase and squash."}}