operation.go

Documentation: k8s.io/kube-openapi/pkg/spec3

     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  	"k8s.io/kube-openapi/pkg/validation/spec"
    26  )
    27  
    28  // Operation describes a single API operation on a path, more at https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#operationObject
    29  //
    30  // Note that this struct is actually a thin wrapper around OperationProps to make it referable and extensible
    31  type Operation struct {
    32  	OperationProps
    33  	spec.VendorExtensible
    34  }
    35  
    36  // MarshalJSON is a custom marshal function that knows how to encode Operation as JSON
    37  func (o *Operation) MarshalJSON() ([]byte, error) {
    38  	if internal.UseOptimizedJSONMarshalingV3 {
    39  		return internal.DeterministicMarshal(o)
    40  	}
    41  	b1, err := json.Marshal(o.OperationProps)
    42  	if err != nil {
    43  		return nil, err
    44  	}
    45  	b2, err := json.Marshal(o.VendorExtensible)
    46  	if err != nil {
    47  		return nil, err
    48  	}
    49  	return swag.ConcatJSON(b1, b2), nil
    50  }
    51  
    52  func (o *Operation) MarshalNextJSON(opts jsonv2.MarshalOptions, enc *jsonv2.Encoder) error {
    53  	var x struct {
    54  		spec.Extensions
    55  		OperationProps operationPropsOmitZero `json:",inline"`
    56  	}
    57  	x.Extensions = internal.SanitizeExtensions(o.Extensions)
    58  	x.OperationProps = operationPropsOmitZero(o.OperationProps)
    59  	return opts.MarshalNext(enc, x)
    60  }
    61  
    62  // UnmarshalJSON hydrates this items instance with the data from JSON
    63  func (o *Operation) UnmarshalJSON(data []byte) error {
    64  	if internal.UseOptimizedJSONUnmarshalingV3 {
    65  		return jsonv2.Unmarshal(data, o)
    66  	}
    67  	if err := json.Unmarshal(data, &o.OperationProps); err != nil {
    68  		return err
    69  	}
    70  	return json.Unmarshal(data, &o.VendorExtensible)
    71  }
    72  
    73  func (o *Operation) UnmarshalNextJSON(opts jsonv2.UnmarshalOptions, dec *jsonv2.Decoder) error {
    74  	var x struct {
    75  		spec.Extensions
    76  		OperationProps
    77  	}
    78  	if err := opts.UnmarshalNext(dec, &x); err != nil {
    79  		return err
    80  	}
    81  	o.Extensions = internal.SanitizeExtensions(x.Extensions)
    82  	o.OperationProps = x.OperationProps
    83  	return nil
    84  }
    85  
    86  // OperationProps describes a single API operation on a path, more at https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#operationObject
    87  type OperationProps struct {
    88  	// Tags holds a list of tags for API documentation control
    89  	Tags []string `json:"tags,omitempty"`
    90  	// Summary holds a short summary of what the operation does
    91  	Summary string `json:"summary,omitempty"`
    92  	// Description holds a verbose explanation of the operation behavior
    93  	Description string `json:"description,omitempty"`
    94  	// ExternalDocs holds additional external documentation for this operation
    95  	ExternalDocs *ExternalDocumentation `json:"externalDocs,omitempty"`
    96  	// OperationId holds a unique string used to identify the operation
    97  	OperationId string `json:"operationId,omitempty"`
    98  	// Parameters a list of parameters that are applicable for this operation
    99  	Parameters []*Parameter `json:"parameters,omitempty"`
   100  	// RequestBody holds the request body applicable for this operation
   101  	RequestBody *RequestBody `json:"requestBody,omitempty"`
   102  	// Responses holds the list of possible responses as they are returned from executing this operation
   103  	Responses *Responses `json:"responses,omitempty"`
   104  	// Deprecated declares this operation to be deprecated
   105  	Deprecated bool `json:"deprecated,omitempty"`
   106  	// SecurityRequirement holds a declaration of which security mechanisms can be used for this operation
   107  	SecurityRequirement []map[string][]string `json:"security,omitempty"`
   108  	// Servers contains an alternative server array to service this operation
   109  	Servers []*Server `json:"servers,omitempty"`
   110  }
   111  
   112  type operationPropsOmitZero struct {
   113  	Tags                []string               `json:"tags,omitempty"`
   114  	Summary             string                 `json:"summary,omitempty"`
   115  	Description         string                 `json:"description,omitempty"`
   116  	ExternalDocs        *ExternalDocumentation `json:"externalDocs,omitzero"`
   117  	OperationId         string                 `json:"operationId,omitempty"`
   118  	Parameters          []*Parameter           `json:"parameters,omitempty"`
   119  	RequestBody         *RequestBody           `json:"requestBody,omitzero"`
   120  	Responses           *Responses             `json:"responses,omitzero"`
   121  	Deprecated          bool                   `json:"deprecated,omitzero"`
   122  	SecurityRequirement []map[string][]string  `json:"security,omitempty"`
   123  	Servers             []*Server              `json:"servers,omitempty"`
   124  }
   125
View as plain text