Enums in the OpenAPI definition

340 views
Skip to first unread message

Gareth Rushgrove

unread,
Aug 10, 2017, 10:25:17 AM8/10/17
to K8s API Machinery SIG
Reference https://github.com/garethr/kubeval/issues/18

(I presume this is a more general issue, but describing a specific
instance below.)

Take Service. This takes a spec.type value which the OpenAPI spec
describes as a string. However if you read the describe it's clear
only certain values are valid:

https://github.com/garethr/kubernetes-json-schema/blob/master/master-standalone/service.json#L140

JSON Schema (and OpenAPI 2 it seems
https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md)
will happily accept this data as an enum:

"enum": ["ExternalName", "ClusterIP", "NodePort", "LoadBalancer"]

Is this understanding correct? Is there a reason this information
isn't encoded in the OpenAPI description at present?

As another example, several descriptions state that strings have to be
a DNS_LABEL. This has a formal regex in the docs, but this isn't
represented in the spec. It's not clear OpenAPI supports regex, which
JSON Schema does, so this second point might be an OpenAPI 2 issue
bubbling through.

Thanks again. I appreciate responses to these.

I'm also tempted to come up with a talk around some of this spelunking
for KubeCon if folks think it might interest more than just me?

Cheers

Gareth


--
Gareth Rushgrove
@garethr

devopsweekly.com
morethanseven.net
garethrushgrove.com

Brian Grant

unread,
Aug 10, 2017, 11:35:48 AM8/10/17
to Gareth Rushgrove, K8s API Machinery SIG
On Thu, Aug 10, 2017 at 7:25 AM, Gareth Rushgrove <gar...@morethanseven.net> wrote:
Reference https://github.com/garethr/kubeval/issues/18

(I presume this is a more general issue, but describing a specific
instance below.)

Take Service. This takes a spec.type value which the OpenAPI spec
describes as a string. However if you read the describe it's clear
only certain values are valid:

https://github.com/garethr/kubernetes-json-schema/blob/master/master-standalone/service.json#L140

JSON Schema (and OpenAPI 2 it seems
https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md)
will happily accept this data as an enum:

 "enum": ["ExternalName", "ClusterIP", "NodePort", "LoadBalancer"]

Is this understanding correct?

Yes.
 
Is there a reason this information
isn't encoded in the OpenAPI description at present?

If you have suggestions about how to represent this, please add them to this issue:
 

As another example, several descriptions state that strings have to be
a DNS_LABEL. This has a formal regex in the docs, but this isn't
represented in the spec. It's not clear OpenAPI supports regex, which
JSON Schema does, so this second point might be an OpenAPI 2 issue
bubbling through.

That's an instance of this:

We started with a Swagger 1.2 generator from another project, which was good enough for a while, but many properties weren't represented. Having help from someone familiar with OpenAPI would be valuable.


Thanks again. I appreciate responses to these.

I'm also tempted to come up with a talk around some of this spelunking
for KubeCon if folks think it might interest more than just me?

A talk about the useful and cool things one could do with the K8s OpenAPI spec would be great. 

The bugs we should just fix or document, if unfixable in OpenAPI 2.
 
 

Cheers

Gareth
--
You received this message because you are subscribed to the Google Groups "K8s API Machinery SIG" group.
To unsubscribe from this group and stop receiving emails from it, send an email to kubernetes-sig-api-machinery+unsub...@googlegroups.com.
To post to this group, send email to kubernetes-sig-api-machinery@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/kubernetes-sig-api-machinery/CAFi_6y%2BOSYVWjRpenYDLMANwssr8d9UnEWoqMdJgFrd7%2BQo6_A%40mail.gmail.com.
For more options, visit https://groups.google.com/d/optout.

Mehdy Bohlool

unread,
Aug 11, 2017, 6:21:22 AM8/11/17
to Brian Grant, Gareth Rushgrove, K8s API Machinery SIG
A talk is a good idea. I was thinking to do a talk on that with focus on some cool things we are doing in kubernetes clients. We should sync up on that.

About enum, as you mentioned, it is completely possible to do it in OpenAPI v2. They only reason we didn't do it was shortage of development cycle. We can come up with a syntax/design and see when we can implement it. Hit me up on slack.



Mehdy Bohlool | Software Engineer | me...@google.com | mbohlool@github 


 
 

Cheers

Gareth
To unsubscribe from this group and stop receiving emails from it, send an email to kubernetes-sig-api-machinery+unsubs...@googlegroups.com.

--
You received this message because you are subscribed to the Google Groups "K8s API Machinery SIG" group.
To unsubscribe from this group and stop receiving emails from it, send an email to kubernetes-sig-api-machinery+unsub...@googlegroups.com.
To post to this group, send email to kubernetes-sig-api-machinery@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/kubernetes-sig-api-machinery/CAKCBhs5VmaPt9UzRL8xhNNJsFM2jRF6ZTX1S7xukWOzbqydWww%40mail.gmail.com.
Reply all
Reply to author
Forward
0 new messages