Improve the output of the swagger API for watch events

pkg/apiserver/api_installer.go

@@ -357,6 +357,12 @@ func (a *APIInstaller) registerResourceHandlers(path string, storage rest.Storag
 			if err := addObjectParams(ws, route, versionedListOptions); err != nil {
 				return err
 			}
+			switch {
+			case isLister && isWatcher:
+				route.Doc("list or watch objects of kind " + kind)
+			case isWatcher:
+				route.Doc("watch objects of kind " + kind)
+			}
 			addParams(route, action.Params)
 			ws.Route(route)
 		case "PUT": // Update a resource.
@@ -405,7 +411,7 @@ func (a *APIInstaller) registerResourceHandlers(path string, storage rest.Storag
 				Doc("watch changes to an object of kind " + kind).
 				Operation("watch" + kind).
 				Produces("application/json").
-				Writes(watchjson.NewWatchEvent())
+				Writes(watchjson.WatchEvent{})
 			if err := addObjectParams(ws, route, versionedListOptions); err != nil {
 				return err
 			}
@@ -418,7 +424,7 @@ func (a *APIInstaller) registerResourceHandlers(path string, storage rest.Storag
 				Doc("watch individual changes to a list of " + kind).
 				Operation("watch" + kind + "list").
 				Produces("application/json").
-				Writes(watchjson.NewWatchEvent())
+				Writes(watchjson.WatchEvent{})
 			if err := addObjectParams(ws, route, versionedListOptions); err != nil {
 				return err
 			}

pkg/watch/json/decoder.go

@@ -46,7 +46,7 @@ func NewDecoder(r io.ReadCloser, codec runtime.Codec) *Decoder {
 // Decode blocks until it can return the next object in the writer. Returns an error
 // if the writer is closed or an object can't be decoded.
 func (d *Decoder) Decode() (watch.EventType, runtime.Object, error) {
-	var got watchEvent
+	var got WatchEvent
 	if err := d.decoder.Decode(&got); err != nil {
 		return "", nil, err
 	}

pkg/watch/json/decoder_test.go

@@ -42,7 +42,7 @@ func TestDecoder(t *testing.T) {
 			if err != nil {
 				t.Fatalf("Unexpected error %v", err)
 			}
-			if err := encoder.Encode(&watchEvent{eventType, runtime.RawExtension{json.RawMessage(data)}}); err != nil {
+			if err := encoder.Encode(&WatchEvent{eventType, runtime.RawExtension{json.RawMessage(data)}}); err != nil {
 				t.Errorf("Unexpected error %v", err)
 			}
 			in.Close()

pkg/watch/json/encoder.go

@@ -25,7 +25,7 @@ import (
 )
 
 // Encoder implements the json.Encoder interface for io.Writers that
-// should serialize watchEvent objects into JSON. It will encode any object
+// should serialize WatchEvent objects into JSON. It will encode any object
 // registered in the supplied codec and return an error otherwies.
 type Encoder struct {
 	w       io.Writer

pkg/watch/json/types.go

@@ -25,21 +25,18 @@ import (
 	"github.com/GoogleCloudPlatform/kubernetes/pkg/watch"
 )
 
-// watchEvent objects are streamed from the api server in response to a watch request.
-// These are not API objects and are unversioned today.
-type watchEvent struct {
-	// The type of the watch event; added, modified, or deleted.
-	Type watch.EventType `json:"type,omitempty"`
+// WatchEvent objects are streamed from the api server in response to a watch request.
+// These are not API objects and may not be changed in a backward-incompatible way.
+// TODO: move to a public, versioned object now that RawExtension conversions are possible
+// in the schema.
+type WatchEvent struct {
+	// The type of the watch event; added, modified, deleted, or error.
+	Type watch.EventType `json:"type,omitempty" description:"the type of watch event; may be ADDED, MODIFIED, DELETED, or ERROR"`
 
 	// For added or modified objects, this is the new object; for deleted objects,
 	// it's the state of the object immediately prior to its deletion.
 	// For errors, it's an api.Status.
-	Object runtime.RawExtension `json:"object,omitempty"`
-}
-
-// NewWatchEvent returns the serialization form of watchEvent for structured schemas
-func NewWatchEvent() interface{} {
-	return &watchEvent{}
+	Object runtime.RawExtension `json:"object,omitempty" description:"the object being watched; will match the type of the resource endpoint or be a Status object if the type is ERROR"`
 }
 
 // Object converts a watch.Event into an appropriately serializable JSON object
@@ -52,5 +49,5 @@ func Object(codec runtime.Codec, event *watch.Event) (interface{}, error) {
 	if err != nil {
 		return nil, err
 	}
-	return &watchEvent{event.Type, runtime.RawExtension{json.RawMessage(data)}}, nil
+	return &WatchEvent{event.Type, runtime.RawExtension{json.RawMessage(data)}}, nil
 }