Generating API reference docs for federation apiserver #31759

nikhiljindal · 2016-08-31T00:29:09Z

Adding a script update-federation-api-reference-docs.sh similar to the existing update-api-reference-docs.sh for kube-apiserver. Have moved the common parts to hack/lib/swagger.sh.
The new script will produce API reference docs for federation-apiserver.

Next step will be to surface these docs at kubernetes.io.

cc @kubernetes/sig-cluster-federation @kubernetes/sig-api-machinery @caesarxuchao

This change is

…uncs for federation gvs

k8s-bot · 2016-08-31T00:30:46Z

Can one of the admins verify that this patch is reasonable to test? If so, please reply "ok to test".
(Note: "add to whitelist" is no longer supported. Please update configurations in kubernetes/test-infra/jenkins/job-configs/kubernetes-jenkins-pull instead.)

This message will repeat several times in short succession due to jenkinsci/ghprb-plugin#292. Sorry.

k8s-bot · 2016-08-31T00:31:05Z

Can one of the admins verify that this patch is reasonable to test? If so, please reply "ok to test".
(Note: "add to whitelist" is no longer supported. Please update configurations in kubernetes/test-infra/jenkins/job-configs/kubernetes-jenkins-pull instead.)

This message will repeat several times in short succession due to jenkinsci/ghprb-plugin#292. Sorry.

k8s-bot · 2016-08-31T00:33:31Z

Can one of the admins verify that this patch is reasonable to test? If so, please reply "ok to test".
(Note: "add to whitelist" is no longer supported. Please update configurations in kubernetes/test-infra/jenkins/job-configs/kubernetes-jenkins-pull instead.)

This message will repeat several times in short succession due to jenkinsci/ghprb-plugin#292. Sorry.

nikhiljindal · 2016-08-31T00:34:25Z

@k8s-bot ok to test

nikhiljindal · 2016-08-31T00:36:40Z

URLs to view the generated files:

https://htmlpreview.github.io/?https://raw.githubusercontent.com/nikhiljindal/kubernetes/fedSwaggerDoc/federation/docs/api-reference/federation/v1beta1/operations.html

https://htmlpreview.github.io/?https://raw.githubusercontent.com/nikhiljindal/kubernetes/fedSwaggerDoc/federation/docs/api-reference/federation/v1beta1/definitions.html

https://htmlpreview.github.io/?https://raw.githubusercontent.com/nikhiljindal/kubernetes/fedSwaggerDoc/federation/docs/api-reference/extensions/v1beta1/operations.html

https://htmlpreview.github.io/?https://raw.githubusercontent.com/nikhiljindal/kubernetes/fedSwaggerDoc/federation/docs/api-reference/extensions/v1beta1/definitions.html

https://htmlpreview.github.io/?https://raw.githubusercontent.com/nikhiljindal/kubernetes/fedSwaggerDoc/federation/docs/api-reference/v1/operations.html

https://htmlpreview.github.io/?https://raw.githubusercontent.com/nikhiljindal/kubernetes/fedSwaggerDoc/federation/docs/api-reference/v1/definitions.html

caesarxuchao · 2016-08-31T03:26:23Z

federation/apis/swagger-spec/api.json

@@ -3,6 +3,10 @@
  "apiVersion": "",
  "basePath": "https://10.10.10.10:6443",
  "resourcePath": "/api",
+  "info": {


What is this?

These got added as a result of #30914.

These fields are part of the spec, go-restful might have recently added support for it.

caesarxuchao · 2016-08-31T04:02:49Z

Review status: 0 of 22 files reviewed at latest revision, 5 unresolved discussions.

hack/update-api-reference-docs.sh, line 38 [r2] (raw file):

GROUP_VERSIONS=("v1" "extensions/v1beta1" "batch/v1" "autoscaling/v1" "certificates/v1alpha1")
GV_DIRS=()

This looks to be copied from the original code, but I think using kube::util::group-version-to-pkg-path will make it cleaner.

hack/update-federation-api-reference-docs.sh, line 40 [r2] (raw file):

GROUP_VERSIONS=("federation/v1beta1" "v1" "extensions/v1beta1")
GV_DIRS=()
for gv in "${GROUP_VERSIONS[@]}"; do

Same here, using kube::util::group-version-to-pkg-path seems better.

hack/lib/swagger.sh, line 79 [r2] (raw file):

  echo "Generating API reference docs for group versions: ${GROUP_VERSIONS[@]}, at dirs: ${GV_DIRS[@]}"
  GROUP_VERSIONS=(${GROUP_VERSIONS[@]})
  GV_DIRS=(${GV_DIRS[@]})

Are these two lines redundant?

Comments from Reviewable

caesarxuchao · 2016-08-31T04:04:10Z

Just some minor comments and a question on what the generated code is.

Review status: 0 of 22 files reviewed at latest revision, 5 unresolved discussions.

Comments from Reviewable

madhusudancs · 2016-08-31T05:16:31Z

A few minor comments, but looks good otherwise. I will however let @caesarxuchao to add the LGTM label.

Reviewed 2 of 14 files at r1.
Review status: 2 of 22 files reviewed at latest revision, 11 unresolved discussions.

federation/apis/swagger-spec/apis.json, line 6 [r1] (raw file):

  "basePath": "https://10.10.10.10:6443",
  "resourcePath": "/apis",
  "info": {

Same as @caesarxuchao's previous comment.

federation/apis/swagger-spec/extensions.json, line 6 [r1] (raw file):

  "basePath": "https://10.10.10.10:6443",
  "resourcePath": "/apis/extensions",
  "info": {

Same as above.

federation/apis/swagger-spec/extensions_v1beta1.json, line 6 [r1] (raw file):

  "basePath": "https://10.10.10.10:6443",
  "resourcePath": "/apis/extensions/v1beta1",
  "info": {

Same as above.

federation/apis/swagger-spec/extensions_v1beta1.json, line 2858 [r1] (raw file):

      "description": "VsphereVolume represents a vSphere volume attached and mounted on kubelets host machine"
     },
     "quobyte": {

A little curious about why this is here.

federation/apis/swagger-spec/federation.json, line 6 [r1] (raw file):

  "basePath": "https://10.10.10.10:6443",
  "resourcePath": "/apis/federation",
  "info": {

Same comment as above and in all the many following occurrences.

hack/update-federation-generated-swagger-docs.sh, line 3 [r1] (raw file):

#!/bin/bash

# Copyright 2015 The Kubernetes Authors.

2016?

Comments from Reviewable

madhusudancs · 2016-08-31T05:37:56Z

https://htmlpreview.github.io/?https://raw.githubusercontent.com/nikhiljindal/kubernetes/fedSwaggerDoc/federation/docs/api-reference/federation/v1beta1/operations.html

https://htmlpreview.github.io/?https://raw.githubusercontent.com/nikhiljindal/kubernetes/fedSwaggerDoc/federation/docs/api-reference/federation/v1beta1/definitions.html

I see a stray *versioned.Event here. What is that supposed to be?

https://htmlpreview.github.io/?https://raw.githubusercontent.com/nikhiljindal/kubernetes/fedSwaggerDoc/federation/docs/api-reference/extensions/v1beta1/operations.html

Articles preceding "Ingress" are all incorrect. For example, create a Ingress should be create an Ingress. Is there a way to fix that?

Do we allow reading the scale subresource in federation? If not we should remove it from this doc here.

Also, the headings for Scale subresources should be fixed. This is also a problem in Kubernetes reference docs, not specific to Federation. For example, read scale of the specified Scale should be read scale of the specified ReplicaSet. I am still not sure if that is correct. I don't know what it means to read "the scale" of a ReplicaSet, but I also don't know what's the correct formation.

Watch documentation ordering is pretty weird. (Also applies to Kubernetes). Any why we list watch in the end and everything else with the corresponding resources?

nikhiljindal · 2016-08-31T18:02:19Z

Review status: 2 of 22 files reviewed at latest revision, 11 unresolved discussions.

federation/apis/swagger-spec/extensions_v1beta1.json, line 2858 [r1] (raw file):

Previously, madhusudancs (Madhusudan.C.S) wrote…

A little curious about why this is here.

This must have been recently added to the PodTemplateSpec. Its here because ReplicaSetSpec includes PodTemplateSpec.

hack/update-api-reference-docs.sh, line 38 [r2] (raw file):

Previously, caesarxuchao (Chao Xu) wrote…

This looks to be copied from the original code, but I think using kube::util::group-version-to-pkg-path will make it cleaner.

Done

hack/update-federation-api-reference-docs.sh, line 40 [r2] (raw file):

Previously, caesarxuchao (Chao Xu) wrote…

Same here, using kube::util::group-version-to-pkg-path seems better.

Done

hack/update-federation-generated-swagger-docs.sh, line 3 [r1] (raw file):

Previously, madhusudancs (Madhusudan.C.S) wrote…

2016?

Fixed

hack/lib/swagger.sh, line 79 [r2] (raw file):

Previously, caesarxuchao (Chao Xu) wrote…

Are these two lines redundant?

No. Without these GROUP_VERSIONS is a single string "v1 extensions/v1beta1". This command turns it into an array.

Comments from Reviewable

nikhiljindal · 2016-08-31T18:14:21Z

https://htmlpreview.github.io/?https://raw.githubusercontent.com/nikhiljindal/kubernetes/fedSwaggerDoc/federation/docs/api-reference/federation/v1beta1/operations.html

https://htmlpreview.github.io/?https://raw.githubusercontent.com/nikhiljindal/kubernetes/fedSwaggerDoc/federation/docs/api-reference/federation/v1beta1/definitions.html
I see a stray *versioned.Event here. What is that supposed to be?

https://htmlpreview.github.io/?https://raw.githubusercontent.com/nikhiljindal/kubernetes/fedSwaggerDoc/federation/docs/api-reference/extensions/v1beta1/operations.html

Articles preceding "Ingress" are all incorrect. For example, create a Ingress should be create an Ingress. Is there a way to fix that?

Yes it is possible to fix it. That doc is generated here:

kubernetes/pkg/apiserver/api_installer.go

Line 599 in 1063731

doc := "create a " + kind

Do we allow reading the scale subresource in federation? If not we should remove it from this doc here.

Yes, we support replicasets/scale:

kubernetes/federation/cmd/federation-apiserver/app/extensions.go

Line 38 in 1063731

"replicasets/scale": replicaSetStorage.Scale,

Also, the headings for Scale subresources should be fixed. This is also a problem in Kubernetes reference docs, not specific to Federation. For example, read scale of the specified Scale should be read scale of the specified ReplicaSet. I am still not sure if that is correct. I don't know what it means to read "the scale" of a ReplicaSet, but I also don't know what's the correct formation.

Watch documentation ordering is pretty weird. (Also applies to Kubernetes). Any why we list watch in the end and everything else with the corresponding resources?

nikhiljindal · 2016-08-31T18:15:04Z

Pushed a new commit as per comments, PTAL.

madhusudancs · 2016-08-31T18:21:22Z

Review status: 2 of 22 files reviewed at latest revision, 11 unresolved discussions.

federation/apis/swagger-spec/extensions_v1beta1.json, line 2858 [r1] (raw file):

Previously, nikhiljindal (Nikhil Jindal) wrote…

This must have been recently added to the PodTemplateSpec. Its here because ReplicaSetSpec includes PodTemplateSpec.

Makes sense.

Also, sorry I did not see this file's path correctly. Reviewable kind of makes it hard. I can't see the full path of the file I am reviewing until I hover on it. So I did not see this was in the federation directory. I was wondering why such a change was not already applied before when someone made the API change in Kubernetes. Now that I see federation/... in the path, it makes sense.

Comments from Reviewable

madhusudancs · 2016-08-31T18:56:31Z

Articles preceding "Ingress" are all incorrect. For example, create a Ingress should be create an Ingress. Is there a way to fix that?

Yes it is possible to fix it. That doc is generated here:

kubernetes/pkg/apiserver/api_installer.go

Line 599 in 1063731

doc := "create a " + kind

Fixing it there would change it for all the resources unless we actually semi-smart article detector right? My question was more on the lines of fixing it only for Ingress.

Do we allow reading the scale subresource in federation? If not we should remove it from this doc here.

Yes, we support replicasets/scale:

kubernetes/federation/cmd/federation-apiserver/app/extensions.go

Line 38 in 1063731

"replicasets/scale": replicaSetStorage.Scale,

Cool! Thanks for confirming.

nikhiljindal · 2016-08-31T19:43:50Z

Articles preceding "Ingress" are all incorrect. For example, create a Ingress should be create an Ingress. Is there a way to fix that?

Yes it is possible to fix it. That doc is generated here:

kubernetes/pkg/apiserver/api_installer.go

Line 599 in 1063731

doc := "create a " + kind

Fixing it there would change it for all the resources unless we actually semi-smart article detector right? My question was more on the lines of fixing it only for Ingress.

Yes, need to use an article detector. Other option will be to add an if there hardcoding ingress :)
But thats the place to set it appropriately.

caesarxuchao · 2016-08-31T20:10:57Z

Thank you both! LGTM.

nikhiljindal · 2016-08-31T20:22:20Z

Squashed the last commit, thanks!

k8s-bot · 2016-08-31T20:59:47Z

GCE e2e build/test passed for commit 633c549.

k8s-github-robot · 2016-08-31T21:53:58Z

@k8s-bot test this [submit-queue is verifying that this PR is safe to merge]

k8s-bot · 2016-08-31T22:30:40Z

GCE e2e build/test passed for commit 633c549.

k8s-github-robot · 2016-08-31T22:33:43Z

Automatic merge from submit-queue

nikhiljindal · 2016-09-01T18:24:28Z

Sent kubernetes/website#1143 to import these docs on k8s.io

@caesarxuchao

Automatic merge from submit-queue Adding a README for federation API ref docs The API ref docs were added in #31759 README makes it easy to link to all other API-ref docs. This is similar to the existing docs/api-reference/README.md for kubernetes. cc @kubernetes/sig-cluster-federation @caesarxuchao

@caesarxuchao

Automatic merge from submit-queue Adding a README for federation API ref docs The API ref docs were added in kubernetes#31759 README makes it easy to link to all other API-ref docs. This is similar to the existing docs/api-reference/README.md for kubernetes. cc @kubernetes/sig-cluster-federation @caesarxuchao (cherry picked from commit e10b061)

@caesarxuchao

Automatic merge from submit-queue Adding a README for federation API ref docs The API ref docs were added in kubernetes#31759 README makes it easy to link to all other API-ref docs. This is similar to the existing docs/api-reference/README.md for kubernetes. cc @kubernetes/sig-cluster-federation @caesarxuchao (cherry picked from commit e10b061)

@caesarxuchao

Automatic merge from submit-queue Adding a README for federation API ref docs The API ref docs were added in kubernetes/kubernetes#31759 README makes it easy to link to all other API-ref docs. This is similar to the existing docs/api-reference/README.md for kubernetes. cc @kubernetes/sig-cluster-federation @caesarxuchao

Adding update-federation-generated-swagger-docs to generate comment f…

a954ff1

…uncs for federation gvs

googlebot added the cla: yes label Aug 31, 2016

nikhiljindal added this to the v1.4 milestone Aug 31, 2016

nikhiljindal added sig/api-machinery Categorizes an issue or PR as relevant to SIG API Machinery. area/cluster-federation release-note-none Denotes a PR that doesn't merit a release note. labels Aug 31, 2016

k8s-github-robot added the size/XXL Denotes a PR that changes 1000+ lines, ignoring generated files. label Aug 31, 2016

nikhiljindal assigned caesarxuchao Aug 31, 2016

caesarxuchao reviewed Aug 31, 2016
View reviewed changes

ghost added kind/documentation Categorizes issue or PR as related to documentation. priority/critical-urgent Highest priority. Must be actively worked on as someone's top priority right now. labels Aug 31, 2016

googlebot added the cla: yes label Aug 31, 2016

caesarxuchao added the lgtm "Looks good to me", indicates that a PR is ready to be merged. label Aug 31, 2016

nikhiljindal added 2 commits August 31, 2016 13:21

Adding a script to update federation API reference docs

209d544

Autogenerated commit by running update-federation-api-reference-docs.sh

633c549

nikhiljindal force-pushed the fedSwaggerDoc branch from f9267c9 to 633c549 Compare August 31, 2016 20:21

nikhiljindal added lgtm "Looks good to me", indicates that a PR is ready to be merged. and removed lgtm "Looks good to me", indicates that a PR is ready to be merged. labels Aug 31, 2016

k8s-github-robot merged commit 199338a into kubernetes:master Aug 31, 2016

This was referenced Sep 13, 2016

Adding a README for federation API ref docs #32612

Merged

1.4: Add federation docs kubernetes/website#1215

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Generating API reference docs for federation apiserver #31759

Generating API reference docs for federation apiserver #31759

nikhiljindal commented Aug 31, 2016 •

edited

Loading

k8s-bot commented Aug 31, 2016

k8s-bot commented Aug 31, 2016

k8s-bot commented Aug 31, 2016

nikhiljindal commented Aug 31, 2016

nikhiljindal commented Aug 31, 2016

caesarxuchao Aug 31, 2016

nikhiljindal Aug 31, 2016

caesarxuchao commented Aug 31, 2016

caesarxuchao commented Aug 31, 2016

madhusudancs commented Aug 31, 2016

madhusudancs commented Aug 31, 2016 •

edited

Loading

nikhiljindal commented Aug 31, 2016

nikhiljindal commented Aug 31, 2016

nikhiljindal commented Aug 31, 2016

madhusudancs commented Aug 31, 2016

madhusudancs commented Aug 31, 2016

nikhiljindal commented Aug 31, 2016

caesarxuchao commented Aug 31, 2016

nikhiljindal commented Aug 31, 2016

k8s-bot commented Aug 31, 2016

k8s-github-robot commented Aug 31, 2016

k8s-bot commented Aug 31, 2016

k8s-github-robot commented Aug 31, 2016

nikhiljindal commented Sep 1, 2016

Generating API reference docs for federation apiserver #31759

Generating API reference docs for federation apiserver #31759

Conversation

nikhiljindal commented Aug 31, 2016 • edited Loading

k8s-bot commented Aug 31, 2016

k8s-bot commented Aug 31, 2016

k8s-bot commented Aug 31, 2016

nikhiljindal commented Aug 31, 2016

nikhiljindal commented Aug 31, 2016

caesarxuchao Aug 31, 2016

Choose a reason for hiding this comment

nikhiljindal Aug 31, 2016

Choose a reason for hiding this comment

caesarxuchao commented Aug 31, 2016

caesarxuchao commented Aug 31, 2016

madhusudancs commented Aug 31, 2016

madhusudancs commented Aug 31, 2016 • edited Loading

nikhiljindal commented Aug 31, 2016

nikhiljindal commented Aug 31, 2016

nikhiljindal commented Aug 31, 2016

madhusudancs commented Aug 31, 2016

madhusudancs commented Aug 31, 2016

nikhiljindal commented Aug 31, 2016

caesarxuchao commented Aug 31, 2016

nikhiljindal commented Aug 31, 2016

k8s-bot commented Aug 31, 2016

k8s-github-robot commented Aug 31, 2016

k8s-bot commented Aug 31, 2016

k8s-github-robot commented Aug 31, 2016

nikhiljindal commented Sep 1, 2016

nikhiljindal commented Aug 31, 2016 •

edited

Loading

madhusudancs commented Aug 31, 2016 •

edited

Loading