From e27a76ae81f7557f3c13d5cd50f758bb5f2b70b0 Mon Sep 17 00:00:00 2001
From: Anastasis Andronidis <anastasis90@yahoo.gr>
Date: Sun, 5 Jul 2015 19:15:36 +0200
Subject: [PATCH] hack and hooks scripts for generating swagger docs

---
 hack/after-build/verify-description.sh        | 67 +++++++++++++++++++
 .../verify-generated-swagger-docs.sh          | 58 ++++++++++++++++
 hack/lib/golang.sh                            |  1 +
 hack/update-generated-swagger-docs.sh         | 66 ++++++++++++++++++
 hack/verify-description.sh                    | 40 ++---------
 hack/verify-generated-swagger-docs.sh         | 28 ++++++++
 hooks/pre-commit                              | 16 ++++-
 7 files changed, 238 insertions(+), 38 deletions(-)
 create mode 100755 hack/after-build/verify-description.sh
 create mode 100755 hack/after-build/verify-generated-swagger-docs.sh
 create mode 100755 hack/update-generated-swagger-docs.sh
 create mode 100755 hack/verify-generated-swagger-docs.sh

diff --git a/hack/after-build/verify-description.sh b/hack/after-build/verify-description.sh
new file mode 100755
index 0000000000..295bdd4bfd
--- /dev/null
+++ b/hack/after-build/verify-description.sh
@@ -0,0 +1,67 @@
+#!/bin/bash
+
+# Copyright 2014 The Kubernetes Authors All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+set -o errexit
+set -o nounset
+set -o pipefail
+
+KUBE_ROOT=$(dirname "${BASH_SOURCE}")/../..
+source "${KUBE_ROOT}/hack/lib/init.sh"
+
+kube::golang::setup_env
+
+# Find binary
+genswaggertypedocs=$(kube::util::find-binary "genswaggertypedocs")
+
+result=0
+
+find_files() {
+  find . -not \( \
+      \( \
+        -wholename './output' \
+        -o -wholename './_output' \
+        -o -wholename './release' \
+        -o -wholename './target' \
+        -o -wholename '*/third_party/*' \
+        -o -wholename '*/Godeps/*' \
+      \) -prune \
+    \) -wholename '*pkg/api/v*/types.go'
+}
+
+if [[ $# -eq 0 ]]; then
+  versioned_api_files=`find_files | egrep "pkg/api/v.[^/]*/types\.go"`
+else
+  versioned_api_files=("${@}")
+fi
+
+for file in $versioned_api_files; do
+  $genswaggertypedocs -v -s "${file}" -f - || result=$?
+  if [[ "${result}" -ne "0" ]]; then
+    echo "API file: ${file} is missing: ${result} descriptions"
+  fi
+  if grep json: "${file}" | grep -v // | grep description: ; then
+    echo "API file: ${file} should not contain descriptions in struct tags"
+    result=1
+  fi
+done
+
+internal_types_file="${KUBE_ROOT}/pkg/api/types.go"
+if grep json: "${internal_types_file}" | grep -v // | grep description: ; then
+  echo "Internal API types should not contain descriptions"
+  result=1
+fi
+
+exit ${result}
diff --git a/hack/after-build/verify-generated-swagger-docs.sh b/hack/after-build/verify-generated-swagger-docs.sh
new file mode 100755
index 0000000000..873e808cac
--- /dev/null
+++ b/hack/after-build/verify-generated-swagger-docs.sh
@@ -0,0 +1,58 @@
+#!/bin/bash
+
+# Copyright 2014 The Kubernetes Authors All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+set -o errexit
+set -o nounset
+set -o pipefail
+
+KUBE_ROOT=$(dirname "${BASH_SOURCE}")/../..
+source "${KUBE_ROOT}/hack/lib/init.sh"
+
+kube::golang::setup_env
+
+# Find binary
+genswaggertypedocs=$(kube::util::find-binary "genswaggertypedocs")
+
+if [[ ! -x "$genswaggertypedocs" ]]; then
+  {
+    echo "It looks as if you don't have a compiled genswaggertypedocs binary"
+    echo
+    echo "If you are running from a clone of the git repo, please run"
+    echo "'./hack/build-go.sh cmd/genswaggertypedocs'."
+  } >&2
+  exit 1
+fi
+
+APIROOT="${KUBE_ROOT}/pkg/api"
+TMP_APIROOT="${KUBE_ROOT}/_tmp/api"
+_tmp="${KUBE_ROOT}/_tmp"
+
+mkdir -p "${_tmp}"
+cp -a "${APIROOT}" "${TMP_APIROOT}"
+
+"${KUBE_ROOT}/hack/update-generated-swagger-docs.sh"
+echo "diffing ${APIROOT} against freshly generated swagger type documentation"
+ret=0
+diff -Naupr -I 'Auto generated by' "${APIROOT}" "${TMP_APIROOT}" || ret=$?
+cp -a ${TMP_APIROOT} "${KUBE_ROOT}/pkg"
+rm -rf "${_tmp}"
+if [[ $ret -eq 0 ]]
+then
+  echo "${APIROOT} up to date."
+else
+  echo "${APIROOT} is out of date. Please run hack/update-generated-swagger-docs.sh"
+  exit 1
+fi
diff --git a/hack/lib/golang.sh b/hack/lib/golang.sh
index 7addc1f809..c3daf257c5 100755
--- a/hack/lib/golang.sh
+++ b/hack/lib/golang.sh
@@ -68,6 +68,7 @@ kube::golang::test_targets() {
     cmd/genbashcomp
     cmd/genconversion
     cmd/gendeepcopy
+    cmd/genswaggertypedocs
     examples/k8petstore/web-server
     github.com/onsi/ginkgo/ginkgo
     test/e2e/e2e.test
diff --git a/hack/update-generated-swagger-docs.sh b/hack/update-generated-swagger-docs.sh
new file mode 100755
index 0000000000..173f696131
--- /dev/null
+++ b/hack/update-generated-swagger-docs.sh
@@ -0,0 +1,66 @@
+#!/bin/bash
+
+# Copyright 2015 The Kubernetes Authors All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+set -o errexit
+set -o nounset
+set -o pipefail
+
+KUBE_ROOT=$(dirname "${BASH_SOURCE}")/..
+source "${KUBE_ROOT}/hack/lib/init.sh"
+
+kube::golang::setup_env
+
+function generate_version() {
+	local version=$1
+	local TMPFILE="/tmp/types_swagger_doc_generated.$(date +%s).go"
+
+	echo "Generating swagger type docs for version ${version}"
+
+	sed 's/YEAR/2015/' hack/boilerplate/boilerplate.go.txt > $TMPFILE
+  echo "package ${version}" >> $TMPFILE
+	cat >> $TMPFILE <<EOF
+
+// This file contains a collection of methods that can be used from go-resful to
+// generate Swagger API documentation for its models. Please read this PR for more
+// information on the implementation: https://github.com/emicklei/go-restful/pull/215
+//
+// TODOs are ignored from the parser. (e.g. TODO(andronat):... || TODO:...) iff
+// are on one line! For multiple line or blocks that you want to ignore use ---.
+// Any context after a --- is ignored.
+//
+// Those methods can be generated by using hack/update-generated-swagger-docs.sh
+
+// AUTO-GENERATED FUNCTIONS START HERE
+EOF
+
+	GOPATH=$(godep path):$GOPATH go run cmd/genswaggertypedocs/swagger_type_docs.go -s "pkg/api/${version}/types.go" -f - >>  $TMPFILE
+
+	echo "// AUTO-GENERATED FUNCTIONS END HERE" >> $TMPFILE
+
+	gofmt -w -s $TMPFILE
+	mv $TMPFILE "pkg/api/${version}/types_swagger_doc_generated.go"
+}
+
+VERSIONS="v1"
+# To avoid compile errors, remove the currently existing files.
+for ver in $VERSIONS; do
+	rm -f "pkg/api/${ver}/types_swagger_doc_generated.go"
+done
+for ver in $VERSIONS; do
+	generate_version "${ver}"
+done
+
+"${KUBE_ROOT}/hack/update-swagger-spec.sh"
diff --git a/hack/verify-description.sh b/hack/verify-description.sh
index 2bb261305f..86a7bc269d 100755
--- a/hack/verify-description.sh
+++ b/hack/verify-description.sh
@@ -19,43 +19,11 @@ set -o nounset
 set -o pipefail
 
 KUBE_ROOT=$(dirname "${BASH_SOURCE}")/..
+source "${KUBE_ROOT}/hack/lib/init.sh"
 
-cd "${KUBE_ROOT}"
+kube::golang::setup_env
+"${KUBE_ROOT}/hack/build-go.sh" cmd/genswaggertypedocs
 
-result=0
-
-find_files() {
-  find . -not \( \
-      \( \
-        -wholename './output' \
-        -o -wholename './_output' \
-        -o -wholename './release' \
-        -o -wholename './target' \
-        -o -wholename '*/third_party/*' \
-        -o -wholename '*/Godeps/*' \
-      \) -prune \
-    \) -wholename '*pkg/api/v*/types.go'
-}
-
-if [[ $# -eq 0 ]]; then
-  versioned_api_files=`find_files | egrep "pkg/api/v.[^/]*/types\.go"`
-else
-  versioned_api_files=("${@}")
-fi
-
-for file in $versioned_api_files; do
-  if grep json: "${file}" | grep -v // | grep -v ,inline | grep -v -q description: ; then
-    echo "API file is missing the required field descriptions: ${file}"
-    result=1
-  fi
-done
-
-internal_types_file="${KUBE_ROOT}/pkg/api/types.go"
-if grep json: "${internal_types_file}" | grep -v // | grep description: ; then
-  echo "Internal API types should not contain descriptions"
-  result=1
-fi
-
-exit ${result}
+"${KUBE_ROOT}/hack/after-build/verify-description.sh" "$@"
 
 # ex: ts=2 sw=2 et filetype=sh
diff --git a/hack/verify-generated-swagger-docs.sh b/hack/verify-generated-swagger-docs.sh
new file mode 100755
index 0000000000..2bd11f784a
--- /dev/null
+++ b/hack/verify-generated-swagger-docs.sh
@@ -0,0 +1,28 @@
+#!/bin/bash
+
+# Copyright 2015 The Kubernetes Authors All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+set -o errexit
+set -o nounset
+set -o pipefail
+
+KUBE_ROOT=$(dirname "${BASH_SOURCE}")/..
+source "${KUBE_ROOT}/hack/lib/init.sh"
+
+kube::golang::setup_env
+
+"${KUBE_ROOT}/hack/build-go.sh" cmd/genswaggertypedocs
+
+"${KUBE_ROOT}/hack/after-build/verify-generated-swagger-docs.sh" "$@"
diff --git a/hooks/pre-commit b/hooks/pre-commit
index d7aa6f3e1f..51225a40c9 100755
--- a/hooks/pre-commit
+++ b/hooks/pre-commit
@@ -93,8 +93,8 @@ files_need_description=()
 # Check API schema definitions for field descriptions
 for file in $(git diff --cached --name-only --diff-filter ACM | egrep "pkg/api/v.[^/]*/types\.go" | grep -v "third_party"); do
   # Check for files with fields without description tags
-  descriptionless=$(hack/after-build/verify-description.sh "${file}")
-  if [[ "$descriptionless" != "" ]]; then
+  descriptionless=$(hack/after-build/verify-description.sh "${file}" > /dev/null; echo $?)
+  if [[ "$descriptionless" -ne "0" ]]; then
     files_need_description+=("${file}")
   fi
 done
@@ -158,6 +158,18 @@ else
 fi
 echo "${reset}"
 
+echo -ne "Checking for swagger type documentation that need updating... "
+if ! hack/after-build/verify-generated-swagger-docs.sh > /dev/null; then
+  echo "${red}ERROR!"
+  echo "Swagger type documentation needs to be updated."
+  echo "To regenerate the spec, run:"
+  echo "  hack/update-generated-swagger-docs.sh"
+  exit_code=1
+else
+  echo "${green}OK"
+fi
+echo "${reset}"
+
 echo -ne "Checking for swagger spec that need updating... "
 if ! hack/after-build/verify-swagger-spec.sh > /dev/null; then
   echo "${red}ERROR!"