k8s.io/kube-openapi@v0.0.0-20240228011516-70dd3763d340/pkg/generators/README.md (about)

     1  # Generate OpenAPI definitions
     2  
     3  - To generate definition for a specific type or package add "+k8s:openapi-gen=true" tag to the type/package comment lines.
     4  - To exclude a type or a member from a tagged package/type, add "+k8s:openapi-gen=false" tag to the comment lines.
     5  
     6  # OpenAPI Extensions
     7  
     8  OpenAPI spec can have extensions on types. To define one or more extensions on a type or its member
     9  add `+k8s:openapi-gen=x-kubernetes-$NAME:$VALUE` to the comment lines before type/member. A type/member can
    10  have multiple extensions. The rest of the line in the comment will be used as $VALUE so there is no need to
    11  escape or quote the value string. Extensions can be used to pass more information to client generators or
    12  documentation generators. For example a type might have a friendly name to be displayed in documentation or
    13  being used in a client's fluent interface.
    14  
    15  # Custom OpenAPI type definitions
    16  
    17  Custom types which otherwise don't map directly to OpenAPI can override their
    18  OpenAPI definition by implementing a function named "OpenAPIDefinition" with
    19  the following signature:
    20  
    21  ```go
    22  	import openapi "k8s.io/kube-openapi/pkg/common"
    23  
    24  	// ...
    25  
    26  	type Time struct {
    27  		time.Time
    28  	}
    29  
    30  	func (_ Time) OpenAPIDefinition() openapi.OpenAPIDefinition {
    31  		return openapi.OpenAPIDefinition{
    32  			Schema: spec.Schema{
    33  				SchemaProps: spec.SchemaProps{
    34  					Type:   []string{"string"},
    35  					Format: "date-time",
    36  				},
    37  			},
    38  		}
    39  	}
    40  ```
    41  
    42  Alternatively, the type can avoid the "openapi" import by defining the following
    43  methods. The following example produces the same OpenAPI definition as the
    44  example above:
    45  
    46  ```go
    47      func (_ Time) OpenAPISchemaType() []string { return []string{"string"} }
    48      func (_ Time) OpenAPISchemaFormat() string { return "date-time" }
    49  ```