k8s.io/kube-openapi@v0.0.0-20240228011516-70dd3763d340/pkg/idl/doc.go (about) 1 /* 2 Copyright 2018 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 // The IDL package describes comment directives that may be applied to 18 // API types and fields. 19 package idl 20 21 // ListType annotates a list to further describe its topology. It may 22 // have 3 possible values: "atomic", "map", or "set". Note that there is 23 // no default, and the generation step will fail if a list is found that 24 // is missing the tag. 25 // 26 // This tag MUST only be used on lists, or the generation step will 27 // fail. 28 // 29 // # Atomic 30 // 31 // Example: 32 // 33 // +listType=atomic 34 // 35 // Atomic lists will be entirely replaced when updated. This tag may be 36 // used on any type of list (struct, scalar, ...). 37 // 38 // Using this tag will generate the following OpenAPI extension: 39 // 40 // "x-kubernetes-list-type": "atomic" 41 // 42 // # Map 43 // 44 // Example: 45 // 46 // +listType=map 47 // 48 // These lists are like maps in that their elements have a non-index key 49 // used to identify them. Order is preserved upon merge. Using the map 50 // tag on a list with non-struct elements will result in an error during 51 // the generation step. 52 // 53 // Using this tag will generate the following OpenAPI extension: 54 // 55 // "x-kubernetes-list-type": "map" 56 // 57 // # Set 58 // 59 // Example: 60 // 61 // +listType=set 62 // 63 // Sets are lists that must not have multiple times the same value. Each 64 // value must be a scalar (or another atomic type). 65 // 66 // Using this tag will generate the following OpenAPI extension: 67 // 68 // "x-kubernetes-list-type": "set" 69 type ListType string 70 71 // ListMapKey annotates map lists by specifying the key used as the index of the map. 72 // 73 // This tag MUST only be used on lists that have the listType=map 74 // attribute, or the generation step will fail. Also, the value 75 // specified for this attribute must be a scalar typed field of the 76 // child structure (no nesting is supported). 77 // 78 // An example of how this can be used is shown in the ListType (map) example. 79 // 80 // Example: 81 // 82 // +listMapKey=name 83 // 84 // Using this tag will generate the following OpenAPI extension: 85 // 86 // "x-kubernetes-list-map-key": "name" 87 type ListMapKey string 88 89 // MapType annotates a map to further describe its topology. It may 90 // have one of two values: `atomic` or `granular`. `atomic` means that the entire map is 91 // considered as a whole; actors that wish to update the map can only 92 // entirely replace it. `granular` means that specific values in the map can be 93 // updated separately from other fields. 94 // 95 // By default, a map will be considered as a set of distinct values that 96 // can be updated individually (i.e. the equivalent of `granular`). 97 // This default will still generate an OpenAPI extension with key: "x-kubernetes-map-type". 98 // 99 // This tag MUST only be used on maps, or the generation step will fail. 100 // 101 // # Atomic 102 // 103 // Example: 104 // 105 // +mapType=atomic 106 // 107 // Atomic maps will be entirely replaced when updated. This tag may be 108 // used on any map. 109 // 110 // Using this tag will generate the following OpenAPI extension: 111 // 112 // "x-kubernetes-map-type": "atomic" 113 type MapType string 114 115 // OpenAPIGen needs to be described. 116 type OpenAPIGen string 117 118 // Optional annotates a field to specify it may be omitted. 119 // By default, fields will be marked as required if not otherwise specified. 120 // 121 // Example: 122 // 123 // +optional 124 // 125 // Additionally, the json struct tag directive "omitempty" can be used to imply 126 // the same. 127 // 128 // Example: 129 // 130 // OptionalField `json:"optionalField,omitempty"` 131 type Optional string 132 133 // PatchMergeKey needs to be described. 134 type PatchMergeKey string 135 136 // PatchStrategy needs to be described. 137 type PatchStrategy string 138 139 // StructType annotates a struct to further describe its topology. It may 140 // have one of two values: `atomic` or `granular`. `atomic` means that the entire struct is 141 // considered as a whole; actors that wish to update the struct can only 142 // entirely replace it. `granular` means that specific fields in the struct can be 143 // updated separately from other fields. 144 // 145 // By default, a struct will be considered as a set of distinct values that 146 // can be updated individually (`granular`). 147 // This default will still generate an OpenAPI extension with key: "x-kubernetes-map-type". 148 // 149 // This tag MUST only be used on structs, or the generation step will fail. 150 // 151 // # Atomic 152 // 153 // Example: 154 // 155 // +structType=atomic 156 // 157 // Atomic structs will be entirely replaced when updated. This tag may be 158 // used on any struct. 159 // 160 // Using this tag will generate the following OpenAPI extension: 161 // 162 // "x-kubernetes-map-type": "atomic" 163 type StructType string 164 165 // Union is TBD. 166 type Union string