k8s.io/kube-openapi@v0.0.0-20240228011516-70dd3763d340/pkg/spec3/example.go (about)

     1  /*
     2  Copyright 2021 The Kubernetes Authors.
     3  
     4  Licensed under the Apache License, Version 2.0 (the "License");
     5  you may not use this file except in compliance with the License.
     6  You may obtain a copy of the License at
     7  
     8      http://www.apache.org/licenses/LICENSE-2.0
     9  
    10  Unless required by applicable law or agreed to in writing, software
    11  distributed under the License is distributed on an "AS IS" BASIS,
    12  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    13  See the License for the specific language governing permissions and
    14  limitations under the License.
    15  */
    16  
    17  package spec3
    18  
    19  import (
    20  	"encoding/json"
    21  
    22  	"github.com/go-openapi/swag"
    23  	"k8s.io/kube-openapi/pkg/internal"
    24  	jsonv2 "k8s.io/kube-openapi/pkg/internal/third_party/go-json-experiment/json"
    25  
    26  	"k8s.io/kube-openapi/pkg/validation/spec"
    27  )
    28  
    29  // Example https://swagger.io/specification/#example-object
    30  
    31  type Example struct {
    32  	spec.Refable
    33  	ExampleProps
    34  	spec.VendorExtensible
    35  }
    36  
    37  // MarshalJSON is a custom marshal function that knows how to encode RequestBody as JSON
    38  func (e *Example) MarshalJSON() ([]byte, error) {
    39  	if internal.UseOptimizedJSONMarshalingV3 {
    40  		return internal.DeterministicMarshal(e)
    41  	}
    42  	b1, err := json.Marshal(e.Refable)
    43  	if err != nil {
    44  		return nil, err
    45  	}
    46  	b2, err := json.Marshal(e.ExampleProps)
    47  	if err != nil {
    48  		return nil, err
    49  	}
    50  	b3, err := json.Marshal(e.VendorExtensible)
    51  	if err != nil {
    52  		return nil, err
    53  	}
    54  	return swag.ConcatJSON(b1, b2, b3), nil
    55  }
    56  func (e *Example) MarshalNextJSON(opts jsonv2.MarshalOptions, enc *jsonv2.Encoder) error {
    57  	var x struct {
    58  		Ref          string `json:"$ref,omitempty"`
    59  		ExampleProps `json:",inline"`
    60  		spec.Extensions
    61  	}
    62  	x.Ref = e.Refable.Ref.String()
    63  	x.Extensions = internal.SanitizeExtensions(e.Extensions)
    64  	x.ExampleProps = e.ExampleProps
    65  	return opts.MarshalNext(enc, x)
    66  }
    67  
    68  func (e *Example) UnmarshalJSON(data []byte) error {
    69  	if internal.UseOptimizedJSONUnmarshalingV3 {
    70  		return jsonv2.Unmarshal(data, e)
    71  	}
    72  	if err := json.Unmarshal(data, &e.Refable); err != nil {
    73  		return err
    74  	}
    75  	if err := json.Unmarshal(data, &e.ExampleProps); err != nil {
    76  		return err
    77  	}
    78  	if err := json.Unmarshal(data, &e.VendorExtensible); err != nil {
    79  		return err
    80  	}
    81  	return nil
    82  }
    83  
    84  func (e *Example) UnmarshalNextJSON(opts jsonv2.UnmarshalOptions, dec *jsonv2.Decoder) error {
    85  	var x struct {
    86  		spec.Extensions
    87  		ExampleProps
    88  	}
    89  	if err := opts.UnmarshalNext(dec, &x); err != nil {
    90  		return err
    91  	}
    92  	if err := internal.JSONRefFromMap(&e.Ref.Ref, x.Extensions); err != nil {
    93  		return err
    94  	}
    95  	e.Extensions = internal.SanitizeExtensions(x.Extensions)
    96  	e.ExampleProps = x.ExampleProps
    97  
    98  	return nil
    99  }
   100  
   101  type ExampleProps struct {
   102  	// Summary holds a short description of the example
   103  	Summary string `json:"summary,omitempty"`
   104  	// Description holds a long description of the example
   105  	Description string `json:"description,omitempty"`
   106  	// Embedded literal example.
   107  	Value interface{} `json:"value,omitempty"`
   108  	// A URL that points to the literal example. This provides the capability to reference examples that cannot easily be included in JSON or YAML documents.
   109  	ExternalValue string `json:"externalValue,omitempty"`
   110  }