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
8OpenAPI spec can have extensions on types. To define one or more extensions on a type or its member
9add `+k8s:openapi-gen=x-kubernetes-$NAME:$VALUE` to the comment lines before type/member. A type/member can
10have multiple extensions. The rest of the line in the comment will be used as $VALUE so there is no need to
11escape or quote the value string. Extensions can be used to pass more information to client generators or
12documentation generators. For example a type might have a friendly name to be displayed in documentation or
13being used in a client's fluent interface.
14
15# Custom OpenAPI type definitions
16
17Custom types which otherwise don't map directly to OpenAPI can override their
18OpenAPI definition by implementing a function named "OpenAPIDefinition" with
19the 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
42Alternatively, the type can avoid the "openapi" import by defining the following
43methods. The following example produces the same OpenAPI definition as the
44example above:
45
46```go
47 func (_ Time) OpenAPISchemaType() []string { return []string{"string"} }
48 func (_ Time) OpenAPISchemaFormat() string { return "date-time" }
49```
View as plain text