hack and hooks scripts for generating swagger docs

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}

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

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

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"

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
+"${KUBE_ROOT}/hack/after-build/verify-description.sh" "$@"
-
-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}
 
 # ex: ts=2 sw=2 et filetype=sh

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" "$@"

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}")
+  descriptionless=$(hack/after-build/verify-description.sh "${file}" > /dev/null; echo $?)
-  if [[ "$descriptionless" != "" ]]; then
+  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!"