Change:
Right now we have haphazard comments regarding which fields are read-only/output-only, and many, such as aren't documented at all. Swagger 2.0 actually supports a property tag, but we're using Swagger 1.2, which does not, officially. The official meaning doesn't match what we want, though. fields must not be included in a PUT, which would be painful for clients. We could simply document our convention, however. We should tag fields as readonly. Maybe we could have go-restful automatically add a comment to the description in that case.
/cc
Are there any known obstacles with upgrading to 2.0?
go-restful (the framework that we are using to generate swagger-spec) does not support 2.0 yet:
Disclaimer: for the doc-fix it day, I will be adding the read-only information into the description. This partially resolves this issue, but not entirely. I will unassign myself after description is done.
Note: users can set the node status when creating a node. This is a bug and should be fixed. After fixing that bug, the corresponding description should be updated.

Discussion:
// TODO: UUID on Manifext is deprecated in the future once we are done // with the API refactory. It is required for now to determine the instance // of a Pod. <del> UUID          types.UID     `json:"uuid,omitempty" description:"manifest UUID"` </del> <ins> UUID          types.UID     `json:"uuid,omitempty" description:"manifest UUID, populated by the system, read-only"` </ins> Volumes       []Volume      `json:"volumes" description:"list of volumes that can be mounted by containers belonging to the pod"` Containers    []Container   `json:"containers" description:"list of containers belonging to the pod"` RestartPolicy RestartPolicy `json:"restartPolicy,omitempty" description:"restart policy for all containers within the pod; one of RestartPolicyAlways, RestartPolicyOnFailure, RestartPolicyNever"`

type TypeMeta struct { Kind              string    `json:"kind,omitempty" description:"kind of object, in CamelCase"` ID                string    `json:"id,omitempty" description:"name of the object; must be a DNS_SUBDOMAIN and unique among all objects of the same kind within the same namespace; used in resource URLs"` <del> UID               types.UID `json:"uid,omitempty" description:"UUID assigned by the system upon creation, unique across space and time"` CreationTimestamp util.Time `json:"creationTimestamp,omitempty" description:"RFC 3339 date and time at which the object was created; recorded by the system; null for lists"` SelfLink          string    `json:"selfLink,omitempty" description:"URL for the object"` ResourceVersion   uint64    `json:"resourceVersion,omitempty" description:"string that identifies the internal version of this object that can be used by clients to determine when objects have changed; value must be treated as opaque by clients and passed unmodified back to the server"` </del> <ins> UID               types.UID `json:"uid,omitempty" description:"unique UUID across space and time; populated by the system, read-only"` CreationTimestamp util.Time `json:"creationTimestamp,omitempty" description:"RFC 3339 date and time at which the object was created; populated by the system, read-only; null for lists"` SelfLink          string    `json:"selfLink,omitempty" description:"URL for the object; populated by the system, read-only"` ResourceVersion   uint64    `json:"resourceVersion,omitempty" description:"string that identifies the internal version of this object that can be used by clients to determine when objects have changed; populated by the system, read-only; value must be treated as opaque by clients and passed unmodified back to the server"` </ins> APIVersion        string    `json:"apiVersion,omitempty" description:"version of the schema the object should have"` Namespace         string    `json:"namespace,omitempty" description:"namespace to which the object belongs; must be a DNS_SUBDOMAIN; 'default' by default"`

TypeMeta     `json:",inline"` Labels       map[string]string `json:"labels,omitempty" description:"map of string keys and values that can be used to organize and categorize pods; may match selectors of replication controllers and services"` DesiredState PodState          `json:"desiredState,omitempty" description:"specification of the desired state of the pod"` <del> CurrentState PodState          `json:"currentState,omitempty" description:"current state of the pod"` </del> <ins> CurrentState PodState          `json:"currentState,omitempty" description:"current state of the pod; populated by the system, read-only"` </ins> // NodeSelector is a selector which must be true for the pod to fit on a node NodeSelector map[string]string `json:"nodeSelector,omitempty" description:"selector which must match a node's labels for the pod to be scheduled on that node"` }

type ReplicationController struct { TypeMeta     `json:",inline"` DesiredState ReplicationControllerState `json:"desiredState,omitempty" description:"specification of the desired state of the replication controller"` <del> CurrentState ReplicationControllerState `json:"currentState,omitempty" description:"current state of the replication controller"` </del> <ins> CurrentState ReplicationControllerState `json:"currentState,omitempty" description:"current state of the replication controller; populated by the system, read-only"` </ins> Labels       map[string]string          `json:"labels,omitempty" description:"map of string keys and values that can be used to organize and categorize replication controllers"` }