Merge pull request #20881 from caesarxuchao/refactor-update-api-reference-docs-script

hack/after-build/update-swagger-spec.sh

@@ -64,15 +64,36 @@ APISERVER_PID=$!
 kube::util::wait_for_url "http://127.0.0.1:${API_PORT}/healthz" "apiserver: "
 
 SWAGGER_API_PATH="http://127.0.0.1:${API_PORT}/swaggerapi/"
+DEFAULT_GROUP_VERSIONS="v1 extensions/v1beta1"
+VERSIONS=${VERSIONS:-$DEFAULT_GROUP_VERSIONS}
+
 kube::log::status "Updating " ${SWAGGER_ROOT_DIR}
-curl -fs ${SWAGGER_API_PATH} > ${SWAGGER_ROOT_DIR}/resourceListing.json
-curl -fs ${SWAGGER_API_PATH}version > ${SWAGGER_ROOT_DIR}/version.json
-curl -fs ${SWAGGER_API_PATH}api > ${SWAGGER_ROOT_DIR}/api.json
-curl -fs ${SWAGGER_API_PATH}api/v1 > ${SWAGGER_ROOT_DIR}/v1.json
-curl -fs ${SWAGGER_API_PATH}apis > ${SWAGGER_ROOT_DIR}/apis.json
-curl -fs ${SWAGGER_API_PATH}apis/extensions > ${SWAGGER_ROOT_DIR}/extensions.json
-curl -fs ${SWAGGER_API_PATH}apis/extensions/v1beta1 > ${SWAGGER_ROOT_DIR}/v1beta1.json
 
+for ver in ${VERSIONS}; do
+  # fetch the swagger spec for each group version. 
+  if [[ ${ver} == "v1" ]]; then
+    SUBPATH="api"
+  else
+    SUBPATH="apis"
+  fi
+  SUBPATH="${SUBPATH}/${ver}"
+  SWAGGER_JSON_NAME="$(kube::util::gv-to-swagger-name ${ver}).json"
+  curl -fs "${SWAGGER_API_PATH}${SUBPATH}" > "${SWAGGER_ROOT_DIR}/${SWAGGER_JSON_NAME}"
+  
+  # fetch the swagger spec for the discovery mechanism at group level.
+  if [[ ${ver} == "v1" ]]; then
+    continue 
+  fi
+  SUBPATH="apis/"${ver%/*}
+  SWAGGER_JSON_NAME="${ver%/*}.json"
+  curl -fs "${SWAGGER_API_PATH}${SUBPATH}" > "${SWAGGER_ROOT_DIR}/${SWAGGER_JSON_NAME}"
+done
+
+# fetch swagger specs for other discovery mechanism.
+curl -fs "${SWAGGER_API_PATH}" > "${SWAGGER_ROOT_DIR}/resourceListing.json"
+curl -fs "${SWAGGER_API_PATH}version" > "${SWAGGER_ROOT_DIR}/version.json"
+curl -fs "${SWAGGER_API_PATH}api" > "${SWAGGER_ROOT_DIR}/api.json"
+curl -fs "${SWAGGER_API_PATH}apis" > "${SWAGGER_ROOT_DIR}/apis.json"
 kube::log::status "SUCCESS"
 
 # ex: ts=2 sw=2 et filetype=sh

hack/gen-swagger-doc/gen-swagger-docs.sh

@@ -33,6 +33,7 @@ for i in {1..3}; do
 done
 
 # gendocs takes "input.json" as the input swagger spec.
+# $1 is expected to be <group>_<version>
 cp /swagger-source/"$1".json input.json
 
 ./gradle-2.5/bin/gradle gendocs --info
@@ -41,20 +42,24 @@ cp /swagger-source/"$1".json input.json
 buf="== Top Level API Objects\n\n"
 top_level_models=$(grep GetObjectKind ./register.go | sed 's/func (obj \*\(.*\)) GetObjectKind(\(.*\)) .*/\1/g' \
     | tr -d '()' | tr -d '{}' | tr -d ' ')
+
+# check if the top level models exist in the definitions.adoc. If they exist,
+# their name will be <version>.<model_name>
+VERSION="${1#*_}"
 for m in $top_level_models
 do
-  if grep -xq "=== $1.$m" ./definitions.adoc
+  if grep -xq "=== ${VERSION}.$m" ./definitions.adoc
   then
-    buf+="* <<$1."$m">>\n"
+    buf+="* <<${VERSION}.$m>>\n"
   fi
 done
 sed -i "1i $buf" ./definitions.adoc
 
-#fix the links in .adoc, replace <<x.y>> with link:definitions.html#_x_y[x.y], and lowercase the _x_y part
+# fix the links in .adoc, replace <<x.y>> with link:definitions.html#_x_y[x.y], and lowercase the _x_y part
 sed -i -e 's|<<\(.*\)\.\(.*\)>>|link:#_\L\1_\2\E[\1.\2]|g' ./definitions.adoc
 sed -i -e 's|<<\(.*\)\.\(.*\)>>|link:definitions.html#_\L\1_\2\E[\1.\2]|g' ./paths.adoc
 
-#fix the link to <<any>>
+# fix the link to <<any>>
 sed -i -e 's|<<any>>|link:#_any[any]|g' ./definitions.adoc
 sed -i -e 's|<<any>>|link:definitions.html#_any[any]|g' ./paths.adoc
 

hack/lib/util.sh

@@ -297,4 +297,19 @@ kube::util::group-version-to-pkg-path() {
   esac
 }
 
+# Takes a group/version and returns the swagger-spec file name.
+# default behavior: extensions/v1beta1 -> extensions_v1beta1
+# special case for v1: v1 -> v1
+kube::util::gv-to-swagger-name() {
+  local group_version="$1"
+  case "${group_version}" in
+    v1)
+      echo "v1"
+      ;;
+    *)
+      echo "${group_version%/*}_${group_version#*/}"
+      ;;
+  esac
+}
+
 # ex: ts=2 sw=2 et filetype=sh

hack/update-api-reference-docs.sh

@@ -40,12 +40,12 @@ OUTPUT_TMP="${KUBE_ROOT}/${TMP_SUBPATH}"
 
 echo "Generating api reference docs at ${OUTPUT_TMP}"
 
-V1_TMP_IN_HOST="${OUTPUT_TMP_IN_HOST}/v1/"
-V1_TMP="${OUTPUT_TMP}/v1/"
-mkdir -p ${V1_TMP}
-V1BETA1_TMP_IN_HOST="${OUTPUT_TMP_IN_HOST}/extensions/v1beta1/"
-V1BETA1_TMP="${OUTPUT_TMP}/extensions/v1beta1/"
-mkdir -p ${V1BETA1_TMP}
+DEFAULT_GROUP_VERSIONS="v1 extensions/v1beta1"
+VERSIONS=${VERSIONS:-$DEFAULT_GROUP_VERSIONS}
+for ver in $VERSIONS; do
+  mkdir -p "${OUTPUT_TMP}/${ver}"
+done
+
 SWAGGER_PATH="${REPO_DIR}/api/swagger-spec/"
 
 echo "Reading swagger spec from: ${SWAGGER_PATH}"
@@ -56,13 +56,23 @@ if [[ $(uname) == "Darwin" ]]; then
   user_flags=""
 fi 
 
-docker run ${user_flags} --rm -v $V1_TMP_IN_HOST:/output:z -v ${SWAGGER_PATH}:/swagger-source:z gcr.io/google_containers/gen-swagger-docs:v4.2 \
-    v1 \
-    https://raw.githubusercontent.com/kubernetes/kubernetes/master/pkg/api/v1/register.go
+for ver in $VERSIONS; do
+  TMP_IN_HOST="${OUTPUT_TMP_IN_HOST}/${ver}"
+  REGISTER_FILE_URL="https://raw.githubusercontent.com/kubernetes/kubernetes/master/pkg"
+  if [[ ${ver} == "v1" ]]; then
+    REGISTER_FILE_URL="${REGISTER_FILE_URL}/api/${ver}/register.go"
+  else
+    REGISTER_FILE_URL="${REGISTER_FILE_URL}/apis/${ver}/register.go"
+  fi
+  SWAGGER_JSON_NAME="$(kube::util::gv-to-swagger-name "${ver}")"
 
-docker run ${user_flags} --rm -v $V1BETA1_TMP_IN_HOST:/output:z -v ${SWAGGER_PATH}:/swagger-source:z gcr.io/google_containers/gen-swagger-docs:v4.2 \
-    v1beta1 \
-    https://raw.githubusercontent.com/kubernetes/kubernetes/master/pkg/apis/extensions/v1beta1/register.go
+  docker run ${user_flags} \
+    --rm -v "${TMP_IN_HOST}":/output:z \
+    -v "${SWAGGER_PATH}":/swagger-source:z \
+    gcr.io/google_containers/gen-swagger-docs:v5 \
+    "${SWAGGER_JSON_NAME}" \
+    "${REGISTER_FILE_URL}"
+done
 
 # Check if we actually changed anything
 pushd "${OUTPUT_TMP}" > /dev/null
@@ -93,6 +103,6 @@ done <"${OUTPUT_TMP}/.generated_html"
 echo "Moving api reference docs from ${OUTPUT_TMP} to ${OUTPUT}"
 
 cp -af "${OUTPUT_TMP}"/* "${OUTPUT}"
-rm -r ${OUTPUT_TMP}
+rm -r "${OUTPUT_TMP}"
 
 # ex: ts=2 sw=2 et filetype=sh