Umbrella: Improvements to API documentation

[tonybaloney]

the public API documentation on kubernetes.io is very challenging to understand compared with projects like Docker, OpenStack.

The first and most challenging issue is that all of the API operations
are listed on one massive page, there isn't any grouping or index. I
have to use the browser find to search within the page and guess what
I'm looking for.

The second issue is that the docs are automatically generated so a lot
of the descriptions are not helpful, for example "proxy PUT requests
to Pod" : PUT /api/v1/proxy/namespaces/{namespace}/pods/{name} - I
have no idea what this does or what it is supposed to do.

Third issue is that the models 'required' for each of the fields are
not entirely correct. I was trying to create a pod. The docs say :
http://kubernetes.io/v1.1/docs/api-reference/v1/definitions.html#_v1_pod
that a pod spec is required, but none of the fields are required.
The API returns and gives an error saying fields are missing. I had to
use trial and error to discover which fields are required at a minimum
(turns out, metadata.name, containers[0].name and
containers[0].image).

@caesarxuchao
@brendandburns
@bgrant0607

[caesarxuchao]

Thanks @tonybaloney. I'll send fixes next week.

[bgrant0607]

Related: #14924, #11933, #16095

The problem with PodSpec is that the same type is shared between Pod and PodTemplate.

[caesarxuchao]

The problem with PodSpec is that the same type is shared between Pod and PodTemplate.

@bgrant0607, I don't think this affects if the fields of PodSpec are required, because the validation functions of Pod and PodTemlate both call the same function to validate PodSpec: here and here.

What's our convention for fields that "one of the fields needs to be specified", like this one? Shall we mark both as not required?

[thockin]

We have to mark them both as optional. AFAIK we have no real way to denote
one-of. Maybe we need a new field tag like 'oneof:foobar' and only one
field tagged as such must be set.
On Jan 20, 2016 1:15 PM, "Chao Xu" notifications@github.com wrote:

The problem with PodSpec is that the same type is shared between Pod and
PodTemplate.

@bgrant0607 https://github.com/bgrant0607, I don't think this affects
if the fields of PodSpec are required, because the validation functions
of Pod and PodTemlate both call the same function to validate PodSpec:
here
https://github.com/kubernetes/kubernetes/blob/master/pkg/api/validation/validation.go#L1310
and here
https://github.com/kubernetes/kubernetes/blob/master/pkg/api/validation/validation.go#L1679
.

What's our convention for fields that "one of the fields needs to be
specified", like this one
https://github.com/kubernetes/kubernetes/blob/master/pkg/api/validation/validation.go#L2163?
Shall we mark both as not required?

—
Reply to this email directly or view it on GitHub
#19680 (comment)
.

[bgrant0607]

Also ref: #17404, #17362, #16873, #16550, #16095, #16049, #15910, #15741, #15244, #15128, #14924, #14189, #11933, #11567, #11468, #11332, #11000, #10710, kubernetes/website#38572, #9097, #8528, #6167, #6145, #4934, #4931, #4700, #3714, #3606, #2971, #1963, kubernetes/website#34935, #22904, #22389, #23303, #29681

[nikhiljindal]

Another problem is that we use the same Pod model for different operations like create and update and the validations for both are different.

[bgrant0607]

Also #22389

We've reached the point where we desperately need good API documentation.

cc @lavalamp

[bgrant0607]

Need to replace out-of-date design docs and proposals: #22797

[bgrant0607]

Example API documentation needed: content type: #22904

[bgrant0607]

kubernetes/website#650

[bgrant0607]

Another issue: example value for each field

[timbunce]

The Elasticsearch API documentation is worth a look as an example.

I especially appreciate that it's easy to switch between versions for a given page, e.g. here's the cluster page for version 1.5. At the top of the page is a clear message saying it's an old version and giving a link to the current. On the right is a drop-down making it trivial to switch to other versions of those docs.

Also worth noting is that every section has an "edit" icon inviting readers to correct mistakes (via github edit workflow).

[bgrant0607]

I don't remember whether it is specifically mentioned somewhere else, but we need a developer-facing version of:
https://github.com/kubernetes/kubernetes/blob/master/docs/devel/api-conventions.md

[zhangxiaoyu-zidif]

@bgrant0607
Your https://github.com/kubernetes/kubernetes/blob/master/docs/devel/api-conventions.md
return 404 error now

[zhangxiaoyu-zidif]

I found it in https://github.com/kubernetes/community/blob/master/contributors/devel/api-conventions.md
:)

[fejta-bot]

Issues go stale after 90d of inactivity.
Mark the issue as fresh with /remove-lifecycle stale.
Stale issues rot after an additional 30d of inactivity and eventually close.

Prevent issues from auto-closing with an /lifecycle frozen comment.

If this issue is safe to close now please do so with /close.

Send feedback to sig-testing, kubernetes/test-infra and/or @fejta.
/lifecycle stale

[bgrant0607]

/remove-lifecycle stale

[fejta-bot]

Issues go stale after 90d of inactivity.
Mark the issue as fresh with /remove-lifecycle stale.
Stale issues rot after an additional 30d of inactivity and eventually close.

If this issue is safe to close now please do so with /close.

Send feedback to sig-testing, kubernetes/test-infra and/or fejta.
/lifecycle stale

[thockin]

/lifecycle frozen
/remove-lifecycle stale

[sftim]

Following #19680 (comment) I've logged issue #89094

[tonybaloney]

@thockin this issue is getting a little old :-) Should I close it?

[sftim]

/wg api-expression

[sftim]

I think this issue is worth keeping. However, @tonybaloney, perhaps you'd be willing to update the issue description to account for the changes / improvements / regressions since you opened it?

[thockin]

I think it's still a real issue