Skip to content

Commit e27a76a

Browse files
andronatandronat
committed
hack and hooks scripts for generating swagger docs
1 parent ff2fcd4 commit e27a76a

7 files changed

+238
-38
lines changed

‎hack/after-build/verify-description.sh

+67
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
#!/bin/bash
2+
3+
# Copyright 2014 The Kubernetes Authors All rights reserved.
4+
#
5+
# Licensed under the Apache License, Version 2.0 (the "License");
6+
# you may not use this file except in compliance with the License.
7+
# You may obtain a copy of the License at
8+
#
9+
# http://www.apache.org/licenses/LICENSE-2.0
10+
#
11+
# Unless required by applicable law or agreed to in writing, software
12+
# distributed under the License is distributed on an "AS IS" BASIS,
13+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14+
# See the License for the specific language governing permissions and
15+
# limitations under the License.
16+
17+
set -o errexit
18+
set -o nounset
19+
set -o pipefail
20+
21+
KUBE_ROOT=$(dirname "${BASH_SOURCE}")/../..
22+
source "${KUBE_ROOT}/hack/lib/init.sh"
23+
24+
kube::golang::setup_env
25+
26+
# Find binary
27+
genswaggertypedocs=$(kube::util::find-binary "genswaggertypedocs")
28+
29+
result=0
30+
31+
find_files() {
32+
find . -not \( \
33+
\( \
34+
-wholename './output' \
35+
-o -wholename './_output' \
36+
-o -wholename './release' \
37+
-o -wholename './target' \
38+
-o -wholename '*/third_party/*' \
39+
-o -wholename '*/Godeps/*' \
40+
\) -prune \
41+
\) -wholename '*pkg/api/v*/types.go'
42+
}
43+
44+
if [[ $# -eq 0 ]]; then
45+
versioned_api_files=`find_files | egrep "pkg/api/v.[^/]*/types\.go"`
46+
else
47+
versioned_api_files=("${@}")
48+
fi
49+
50+
for file in $versioned_api_files; do
51+
$genswaggertypedocs -v -s "${file}" -f - || result=$?
52+
if [[ "${result}" -ne "0" ]]; then
53+
echo "API file: ${file} is missing: ${result} descriptions"
54+
fi
55+
if grep json: "${file}" | grep -v // | grep description: ; then
56+
echo "API file: ${file} should not contain descriptions in struct tags"
57+
result=1
58+
fi
59+
done
60+
61+
internal_types_file="${KUBE_ROOT}/pkg/api/types.go"
62+
if grep json: "${internal_types_file}" | grep -v // | grep description: ; then
63+
echo "Internal API types should not contain descriptions"
64+
result=1
65+
fi
66+
67+
exit ${result}

‎hack/after-build/verify-generated-swagger-docs.sh

+58
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
#!/bin/bash
2+
3+
# Copyright 2014 The Kubernetes Authors All rights reserved.
4+
#
5+
# Licensed under the Apache License, Version 2.0 (the "License");
6+
# you may not use this file except in compliance with the License.
7+
# You may obtain a copy of the License at
8+
#
9+
# http://www.apache.org/licenses/LICENSE-2.0
10+
#
11+
# Unless required by applicable law or agreed to in writing, software
12+
# distributed under the License is distributed on an "AS IS" BASIS,
13+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14+
# See the License for the specific language governing permissions and
15+
# limitations under the License.
16+
17+
set -o errexit
18+
set -o nounset
19+
set -o pipefail
20+
21+
KUBE_ROOT=$(dirname "${BASH_SOURCE}")/../..
22+
source "${KUBE_ROOT}/hack/lib/init.sh"
23+
24+
kube::golang::setup_env
25+
26+
# Find binary
27+
genswaggertypedocs=$(kube::util::find-binary "genswaggertypedocs")
28+
29+
if [[ ! -x "$genswaggertypedocs" ]]; then
30+
{
31+
echo "It looks as if you don't have a compiled genswaggertypedocs binary"
32+
echo
33+
echo "If you are running from a clone of the git repo, please run"
34+
echo "'./hack/build-go.sh cmd/genswaggertypedocs'."
35+
} >&2
36+
exit 1
37+
fi
38+
39+
APIROOT="${KUBE_ROOT}/pkg/api"
40+
TMP_APIROOT="${KUBE_ROOT}/_tmp/api"
41+
_tmp="${KUBE_ROOT}/_tmp"
42+
43+
mkdir -p "${_tmp}"
44+
cp -a "${APIROOT}" "${TMP_APIROOT}"
45+
46+
"${KUBE_ROOT}/hack/update-generated-swagger-docs.sh"
47+
echo "diffing ${APIROOT} against freshly generated swagger type documentation"
48+
ret=0
49+
diff -Naupr -I 'Auto generated by' "${APIROOT}" "${TMP_APIROOT}" || ret=$?
50+
cp -a ${TMP_APIROOT} "${KUBE_ROOT}/pkg"
51+
rm -rf "${_tmp}"
52+
if [[ $ret -eq 0 ]]
53+
then
54+
echo "${APIROOT} up to date."
55+
else
56+
echo "${APIROOT} is out of date. Please run hack/update-generated-swagger-docs.sh"
57+
exit 1
58+
fi

‎hack/lib/golang.sh

+1
Original file line numberDiff line numberDiff line change
@@ -68,6 +68,7 @@ kube::golang::test_targets() {
6868
cmd/genbashcomp
6969
cmd/genconversion
7070
cmd/gendeepcopy
71+
cmd/genswaggertypedocs
7172
examples/k8petstore/web-server
7273
github.com/onsi/ginkgo/ginkgo
7374
test/e2e/e2e.test

‎hack/update-generated-swagger-docs.sh

+66
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
#!/bin/bash
2+
3+
# Copyright 2015 The Kubernetes Authors All rights reserved.
4+
#
5+
# Licensed under the Apache License, Version 2.0 (the "License");
6+
# you may not use this file except in compliance with the License.
7+
# You may obtain a copy of the License at
8+
#
9+
# http://www.apache.org/licenses/LICENSE-2.0
10+
#
11+
# Unless required by applicable law or agreed to in writing, software
12+
# distributed under the License is distributed on an "AS IS" BASIS,
13+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14+
# See the License for the specific language governing permissions and
15+
# limitations under the License.
16+
17+
set -o errexit
18+
set -o nounset
19+
set -o pipefail
20+
21+
KUBE_ROOT=$(dirname "${BASH_SOURCE}")/..
22+
source "${KUBE_ROOT}/hack/lib/init.sh"
23+
24+
kube::golang::setup_env
25+
26+
function generate_version() {
27+
local version=$1
28+
local TMPFILE="/tmp/types_swagger_doc_generated.$(date +%s).go"
29+
30+
echo "Generating swagger type docs for version ${version}"
31+
32+
sed 's/YEAR/2015/' hack/boilerplate/boilerplate.go.txt > $TMPFILE
33+
echo "package ${version}" >> $TMPFILE
34+
cat >> $TMPFILE <<EOF
35+
36+
// This file contains a collection of methods that can be used from go-resful to
37+
// generate Swagger API documentation for its models. Please read this PR for more
38+
// information on the implementation: https://github.com/emicklei/go-restful/pull/215
39+
//
40+
// TODOs are ignored from the parser. (e.g. TODO(andronat):... || TODO:...) iff
41+
// are on one line! For multiple line or blocks that you want to ignore use ---.
42+
// Any context after a --- is ignored.
43+
//
44+
// Those methods can be generated by using hack/update-generated-swagger-docs.sh
45+
46+
// AUTO-GENERATED FUNCTIONS START HERE
47+
EOF
48+
49+
GOPATH=$(godep path):$GOPATH go run cmd/genswaggertypedocs/swagger_type_docs.go -s "pkg/api/${version}/types.go" -f - >> $TMPFILE
50+
51+
echo "// AUTO-GENERATED FUNCTIONS END HERE" >> $TMPFILE
52+
53+
gofmt -w -s $TMPFILE
54+
mv $TMPFILE "pkg/api/${version}/types_swagger_doc_generated.go"
55+
}
56+
57+
VERSIONS="v1"
58+
# To avoid compile errors, remove the currently existing files.
59+
for ver in $VERSIONS; do
60+
rm -f "pkg/api/${ver}/types_swagger_doc_generated.go"
61+
done
62+
for ver in $VERSIONS; do
63+
generate_version "${ver}"
64+
done
65+
66+
"${KUBE_ROOT}/hack/update-swagger-spec.sh"

‎hack/verify-description.sh

+4-36
Original file line numberDiff line numberDiff line change
@@ -19,43 +19,11 @@ set -o nounset
1919
set -o pipefail
2020

2121
KUBE_ROOT=$(dirname "${BASH_SOURCE}")/..
22+
source "${KUBE_ROOT}/hack/lib/init.sh"
2223

23-
cd "${KUBE_ROOT}"
24+
kube::golang::setup_env
25+
"${KUBE_ROOT}/hack/build-go.sh" cmd/genswaggertypedocs
2426

25-
result=0
26-
27-
find_files() {
28-
find . -not \( \
29-
\( \
30-
-wholename './output' \
31-
-o -wholename './_output' \
32-
-o -wholename './release' \
33-
-o -wholename './target' \
34-
-o -wholename '*/third_party/*' \
35-
-o -wholename '*/Godeps/*' \
36-
\) -prune \
37-
\) -wholename '*pkg/api/v*/types.go'
38-
}
39-
40-
if [[ $# -eq 0 ]]; then
41-
versioned_api_files=`find_files | egrep "pkg/api/v.[^/]*/types\.go"`
42-
else
43-
versioned_api_files=("${@}")
44-
fi
45-
46-
for file in $versioned_api_files; do
47-
if grep json: "${file}" | grep -v // | grep -v ,inline | grep -v -q description: ; then
48-
echo "API file is missing the required field descriptions: ${file}"
49-
result=1
50-
fi
51-
done
52-
53-
internal_types_file="${KUBE_ROOT}/pkg/api/types.go"
54-
if grep json: "${internal_types_file}" | grep -v // | grep description: ; then
55-
echo "Internal API types should not contain descriptions"
56-
result=1
57-
fi
58-
59-
exit ${result}
27+
"${KUBE_ROOT}/hack/after-build/verify-description.sh" "$@"
6028

6129
# ex: ts=2 sw=2 et filetype=sh

‎hack/verify-generated-swagger-docs.sh

+28
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
#!/bin/bash
2+
3+
# Copyright 2015 The Kubernetes Authors All rights reserved.
4+
#
5+
# Licensed under the Apache License, Version 2.0 (the "License");
6+
# you may not use this file except in compliance with the License.
7+
# You may obtain a copy of the License at
8+
#
9+
# http://www.apache.org/licenses/LICENSE-2.0
10+
#
11+
# Unless required by applicable law or agreed to in writing, software
12+
# distributed under the License is distributed on an "AS IS" BASIS,
13+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14+
# See the License for the specific language governing permissions and
15+
# limitations under the License.
16+
17+
set -o errexit
18+
set -o nounset
19+
set -o pipefail
20+
21+
KUBE_ROOT=$(dirname "${BASH_SOURCE}")/..
22+
source "${KUBE_ROOT}/hack/lib/init.sh"
23+
24+
kube::golang::setup_env
25+
26+
"${KUBE_ROOT}/hack/build-go.sh" cmd/genswaggertypedocs
27+
28+
"${KUBE_ROOT}/hack/after-build/verify-generated-swagger-docs.sh" "$@"

‎hooks/pre-commit

+14-2
Original file line numberDiff line numberDiff line change
@@ -93,8 +93,8 @@ files_need_description=()
9393
# Check API schema definitions for field descriptions
9494
for file in $(git diff --cached --name-only --diff-filter ACM | egrep "pkg/api/v.[^/]*/types\.go" | grep -v "third_party"); do
9595
# Check for files with fields without description tags
96-
descriptionless=$(hack/after-build/verify-description.sh "${file}")
97-
if [[ "$descriptionless" != "" ]]; then
96+
descriptionless=$(hack/after-build/verify-description.sh "${file}" > /dev/null; echo $?)
97+
if [[ "$descriptionless" -ne "0" ]]; then
9898
files_need_description+=("${file}")
9999
fi
100100
done
@@ -158,6 +158,18 @@ else
158158
fi
159159
echo "${reset}"
160160

161+
echo -ne "Checking for swagger type documentation that need updating... "
162+
if ! hack/after-build/verify-generated-swagger-docs.sh > /dev/null; then
163+
echo "${red}ERROR!"
164+
echo "Swagger type documentation needs to be updated."
165+
echo "To regenerate the spec, run:"
166+
echo " hack/update-generated-swagger-docs.sh"
167+
exit_code=1
168+
else
169+
echo "${green}OK"
170+
fi
171+
echo "${reset}"
172+
161173
echo -ne "Checking for swagger spec that need updating... "
162174
if ! hack/after-build/verify-swagger-spec.sh > /dev/null; then
163175
echo "${red}ERROR!"

0 commit comments

Comments
 (0)