header.go

Documentation: github.com/go-openapi/spec

     1  // Copyright 2015 go-swagger maintainers
     2  //
     3  // Licensed under the Apache License, Version 2.0 (the "License");
     4  // you may not use this file except in compliance with the License.
     5  // You may obtain a copy of the License at
     6  //
     7  //    http://www.apache.org/licenses/LICENSE-2.0
     8  //
     9  // Unless required by applicable law or agreed to in writing, software
    10  // distributed under the License is distributed on an "AS IS" BASIS,
    11  // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    12  // See the License for the specific language governing permissions and
    13  // limitations under the License.
    14  
    15  package spec
    16  
    17  import (
    18  	"encoding/json"
    19  	"strings"
    20  
    21  	"github.com/go-openapi/jsonpointer"
    22  	"github.com/go-openapi/swag"
    23  )
    24  
    25  const (
    26  	jsonArray = "array"
    27  )
    28  
    29  // HeaderProps describes a response header
    30  type HeaderProps struct {
    31  	Description string `json:"description,omitempty"`
    32  }
    33  
    34  // Header describes a header for a response of the API
    35  //
    36  // For more information: http://goo.gl/8us55a#headerObject
    37  type Header struct {
    38  	CommonValidations
    39  	SimpleSchema
    40  	VendorExtensible
    41  	HeaderProps
    42  }
    43  
    44  // ResponseHeader creates a new header instance for use in a response
    45  func ResponseHeader() *Header {
    46  	return new(Header)
    47  }
    48  
    49  // WithDescription sets the description on this response, allows for chaining
    50  func (h *Header) WithDescription(description string) *Header {
    51  	h.Description = description
    52  	return h
    53  }
    54  
    55  // Typed a fluent builder method for the type of parameter
    56  func (h *Header) Typed(tpe, format string) *Header {
    57  	h.Type = tpe
    58  	h.Format = format
    59  	return h
    60  }
    61  
    62  // CollectionOf a fluent builder method for an array item
    63  func (h *Header) CollectionOf(items *Items, format string) *Header {
    64  	h.Type = jsonArray
    65  	h.Items = items
    66  	h.CollectionFormat = format
    67  	return h
    68  }
    69  
    70  // WithDefault sets the default value on this item
    71  func (h *Header) WithDefault(defaultValue interface{}) *Header {
    72  	h.Default = defaultValue
    73  	return h
    74  }
    75  
    76  // WithMaxLength sets a max length value
    77  func (h *Header) WithMaxLength(max int64) *Header {
    78  	h.MaxLength = &max
    79  	return h
    80  }
    81  
    82  // WithMinLength sets a min length value
    83  func (h *Header) WithMinLength(min int64) *Header {
    84  	h.MinLength = &min
    85  	return h
    86  }
    87  
    88  // WithPattern sets a pattern value
    89  func (h *Header) WithPattern(pattern string) *Header {
    90  	h.Pattern = pattern
    91  	return h
    92  }
    93  
    94  // WithMultipleOf sets a multiple of value
    95  func (h *Header) WithMultipleOf(number float64) *Header {
    96  	h.MultipleOf = &number
    97  	return h
    98  }
    99  
   100  // WithMaximum sets a maximum number value
   101  func (h *Header) WithMaximum(max float64, exclusive bool) *Header {
   102  	h.Maximum = &max
   103  	h.ExclusiveMaximum = exclusive
   104  	return h
   105  }
   106  
   107  // WithMinimum sets a minimum number value
   108  func (h *Header) WithMinimum(min float64, exclusive bool) *Header {
   109  	h.Minimum = &min
   110  	h.ExclusiveMinimum = exclusive
   111  	return h
   112  }
   113  
   114  // WithEnum sets a the enum values (replace)
   115  func (h *Header) WithEnum(values ...interface{}) *Header {
   116  	h.Enum = append([]interface{}{}, values...)
   117  	return h
   118  }
   119  
   120  // WithMaxItems sets the max items
   121  func (h *Header) WithMaxItems(size int64) *Header {
   122  	h.MaxItems = &size
   123  	return h
   124  }
   125  
   126  // WithMinItems sets the min items
   127  func (h *Header) WithMinItems(size int64) *Header {
   128  	h.MinItems = &size
   129  	return h
   130  }
   131  
   132  // UniqueValues dictates that this array can only have unique items
   133  func (h *Header) UniqueValues() *Header {
   134  	h.UniqueItems = true
   135  	return h
   136  }
   137  
   138  // AllowDuplicates this array can have duplicates
   139  func (h *Header) AllowDuplicates() *Header {
   140  	h.UniqueItems = false
   141  	return h
   142  }
   143  
   144  // WithValidations is a fluent method to set header validations
   145  func (h *Header) WithValidations(val CommonValidations) *Header {
   146  	h.SetValidations(SchemaValidations{CommonValidations: val})
   147  	return h
   148  }
   149  
   150  // MarshalJSON marshal this to JSON
   151  func (h Header) MarshalJSON() ([]byte, error) {
   152  	b1, err := json.Marshal(h.CommonValidations)
   153  	if err != nil {
   154  		return nil, err
   155  	}
   156  	b2, err := json.Marshal(h.SimpleSchema)
   157  	if err != nil {
   158  		return nil, err
   159  	}
   160  	b3, err := json.Marshal(h.HeaderProps)
   161  	if err != nil {
   162  		return nil, err
   163  	}
   164  	return swag.ConcatJSON(b1, b2, b3), nil
   165  }
   166  
   167  // UnmarshalJSON unmarshals this header from JSON
   168  func (h *Header) UnmarshalJSON(data []byte) error {
   169  	if err := json.Unmarshal(data, &h.CommonValidations); err != nil {
   170  		return err
   171  	}
   172  	if err := json.Unmarshal(data, &h.SimpleSchema); err != nil {
   173  		return err
   174  	}
   175  	if err := json.Unmarshal(data, &h.VendorExtensible); err != nil {
   176  		return err
   177  	}
   178  	return json.Unmarshal(data, &h.HeaderProps)
   179  }
   180  
   181  // JSONLookup look up a value by the json property name
   182  func (h Header) JSONLookup(token string) (interface{}, error) {
   183  	if ex, ok := h.Extensions[token]; ok {
   184  		return &ex, nil
   185  	}
   186  
   187  	r, _, err := jsonpointer.GetForToken(h.CommonValidations, token)
   188  	if err != nil && !strings.HasPrefix(err.Error(), "object has no field") {
   189  		return nil, err
   190  	}
   191  	if r != nil {
   192  		return r, nil
   193  	}
   194  	r, _, err = jsonpointer.GetForToken(h.SimpleSchema, token)
   195  	if err != nil && !strings.HasPrefix(err.Error(), "object has no field") {
   196  		return nil, err
   197  	}
   198  	if r != nil {
   199  		return r, nil
   200  	}
   201  	r, _, err = jsonpointer.GetForToken(h.HeaderProps, token)
   202  	return r, err
   203  }
   204
View as plain text