refine api docs

Signed-off-by: hongming <talonwan@yunify.com>

vendor/github.com/emicklei/go-restful/route_builder.go

@@ -17,14 +17,15 @@ import (
 
 // RouteBuilder is a helper to construct Routes.
 type RouteBuilder struct {
-	rootPath    string
-	currentPath string
-	produces    []string
-	consumes    []string
-	httpMethod  string        // required
-	function    RouteFunction // required
-	filters     []FilterFunction
-	conditions  []RouteSelectionConditionFunction
+	rootPath                         string
+	currentPath                      string
+	produces                         []string
+	consumes                         []string
+	httpMethod                       string        // required
+	function                         RouteFunction // required
+	filters                          []FilterFunction
+	conditions                       []RouteSelectionConditionFunction
+	allowedMethodsWithoutContentType []string // see Route
 
 	typeNameHandleFunc TypeNameHandleFunction // required
 
@@ -176,6 +177,15 @@ func (b *RouteBuilder) Returns(code int, message string, model interface{}) *Rou
 	return b
 }
 
+// ReturnsWithHeaders is similar to Returns, but can specify response headers
+func (b *RouteBuilder) ReturnsWithHeaders(code int, message string, model interface{}, headers map[string]Header) *RouteBuilder {
+	b.Returns(code, message, model)
+	err := b.errorMap[code]
+	err.Headers = headers
+	b.errorMap[code] = err
+	return b
+}
+
 // DefaultReturns is a special Returns call that sets the default of the response.
 func (b *RouteBuilder) DefaultReturns(message string, model interface{}) *RouteBuilder {
 	b.defaultResponse = &ResponseError{
@@ -200,14 +210,41 @@ func (b *RouteBuilder) Deprecate() *RouteBuilder {
 	return b
 }
 
+// AllowedMethodsWithoutContentType overides the default list GET,HEAD,OPTIONS,DELETE,TRACE
+// If a request does not include a content-type header then
+// depending on the method, it may return a 415 Unsupported Media.
+// Must have uppercase HTTP Method names such as GET,HEAD,OPTIONS,...
+func (b *RouteBuilder) AllowedMethodsWithoutContentType(methods []string) *RouteBuilder {
+	b.allowedMethodsWithoutContentType = methods
+	return b
+}
+
 // ResponseError represents a response; not necessarily an error.
 type ResponseError struct {
 	Code      int
 	Message   string
 	Model     interface{}
+	Headers   map[string]Header
 	IsDefault bool
 }
 
+// Header describes a header for a response of the API
+//
+// For more information: http://goo.gl/8us55a#headerObject
+type Header struct {
+	*Items
+	Description string
+}
+
+// Items describe swagger simple schemas for headers
+type Items struct {
+	Type             string
+	Format           string
+	Items            *Items
+	CollectionFormat string
+	Default          interface{}
+}
+
 func (b *RouteBuilder) servicePath(path string) *RouteBuilder {
 	b.rootPath = path
 	return b
@@ -276,26 +313,27 @@ func (b *RouteBuilder) Build() Route {
 		operationName = nameOfFunction(b.function)
 	}
 	route := Route{
-		Method:                 b.httpMethod,
-		Path:                   concatPath(b.rootPath, b.currentPath),
-		Produces:               b.produces,
-		Consumes:               b.consumes,
-		Function:               b.function,
-		Filters:                b.filters,
-		If:                     b.conditions,
-		relativePath:           b.currentPath,
-		pathExpr:               pathExpr,
-		Doc:                    b.doc,
-		Notes:                  b.notes,
-		Operation:              operationName,
-		ParameterDocs:          b.parameters,
-		ResponseErrors:         b.errorMap,
-		DefaultResponse:        b.defaultResponse,
-		ReadSample:             b.readSample,
-		WriteSample:            b.writeSample,
-		Metadata:               b.metadata,
-		Deprecated:             b.deprecated,
-		contentEncodingEnabled: b.contentEncodingEnabled,
+		Method:                           b.httpMethod,
+		Path:                             concatPath(b.rootPath, b.currentPath),
+		Produces:                         b.produces,
+		Consumes:                         b.consumes,
+		Function:                         b.function,
+		Filters:                          b.filters,
+		If:                               b.conditions,
+		relativePath:                     b.currentPath,
+		pathExpr:                         pathExpr,
+		Doc:                              b.doc,
+		Notes:                            b.notes,
+		Operation:                        operationName,
+		ParameterDocs:                    b.parameters,
+		ResponseErrors:                   b.errorMap,
+		DefaultResponse:                  b.defaultResponse,
+		ReadSample:                       b.readSample,
+		WriteSample:                      b.writeSample,
+		Metadata:                         b.metadata,
+		Deprecated:                       b.deprecated,
+		contentEncodingEnabled:           b.contentEncodingEnabled,
+		allowedMethodsWithoutContentType: b.allowedMethodsWithoutContentType,
 	}
 	route.postBuild()
 	return route