Matthias Andreas Benkard | 832a54e | 2019-01-29 09:27:38 +0100 | [diff] [blame] | 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 | OpenAPI spec can have extensions on types. To define one or more extensions on a type or its member |
| 8 | add `+k8s:openapi-gen=x-kubernetes-$NAME:`$VALUE`` to the comment lines before type/member. A type/member can |
| 9 | have multiple extensions. The rest of the line in the comment will be used as $VALUE so there is no need to |
| 10 | escape or quote the value string. Extensions can be used to pass more information to client generators or |
| 11 | documentation generators. For example a type might have a friendly name to be displayed in documentation or |
| 12 | being used in a client's fluent interface. |
| 13 | |
| 14 | # Custom OpenAPI type definitions |
| 15 | |
| 16 | Custom types which otherwise don't map directly to OpenAPI can override their |
| 17 | OpenAPI definition by implementing a function named "OpenAPIDefinition" with |
| 18 | the following signature: |
| 19 | |
| 20 | import openapi "k8s.io/kube-openapi/pkg/common" |
| 21 | |
| 22 | // ... |
| 23 | |
| 24 | type Time struct { |
| 25 | time.Time |
| 26 | } |
| 27 | |
| 28 | func (_ Time) OpenAPIDefinition() openapi.OpenAPIDefinition { |
| 29 | return openapi.OpenAPIDefinition{ |
| 30 | Schema: spec.Schema{ |
| 31 | SchemaProps: spec.SchemaProps{ |
| 32 | Type: []string{"string"}, |
| 33 | Format: "date-time", |
| 34 | }, |
| 35 | }, |
| 36 | } |
| 37 | } |
| 38 | |
| 39 | Alternatively, the type can avoid the "openapi" import by defining the following |
| 40 | methods. The following example produces the same OpenAPI definition as the |
| 41 | example above: |
| 42 | |
| 43 | func (_ Time) OpenAPISchemaType() []string { return []string{"string"} } |
| 44 | func (_ Time) OpenAPISchemaFormat() string { return "date-time" } |
| 45 | |
| 46 | TODO(mehdy): Make k8s:openapi-gen a parameter to the generator now that OpenAPI has its own repo. |