Nail/fission-src
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Optimize swagger doc generator for Fission CR types (#2123)

Browse Source 
Signed-off-by: Sanket Sudake <sanketsudake@gmail.com>
This commit is contained in:
Sanket Sudake
2021-07-22 19:05:37 +05:30
committed by GitHub
parent d4d58e166b
commit a7f819a78e
15 changed files with 92 additions and 187 deletions
Download Patch File Download Diff File Expand all files Collapse all files
pkg/apis/boilerplate.txt
-15
View File
@@ -1,15 +0,0 @@
/*
Copyright The Fission Authors.
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.
*/
pkg/apis/core/v1/tool/README.md
-7
View File
@@ -1,7 +0,0 @@
# How to update swagger (OpenAPI) struct description
Run `update-generated-swagger-docs.sh` and it will parse all comments in `types.go`.
```bash
./update-generated-swagger-docs.sh
```
pkg/apis/core/v1/tool/boilerplate.generatego.txt
-15
View File
@@ -1,15 +0,0 @@
/*
Copyright 2019 The Fission Authors.
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.
*/
pkg/apis/core/v1/tool/swagger.sh
-67
View File
@@ -1,67 +0,0 @@
#!/usr/bin/env bash
# Copyright 2016 The Kubernetes Authors.
#
# 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.
#
# Please refer https://github.com/kubernetes/kubernetes/tree/master/hack for original file
#
# Contains swagger related util functions.
#
set -o errexit
set -o nounset
set -o pipefail
# Generates types_swagger_doc_generated file for the given group version.
# $1: Name of the group version
# $2: Path to the directory where types.go for that group version exists. This
# is the directory where the file will be generated.
kube::swagger::gen_types_swagger_doc() {
local group_version=$1
local gv_dir=$2
local TMPFILE
TMPFILE="${TMPDIR:-/tmp}/types_swagger_doc_generated.$(date +%s).go"
echo "Generating swagger type docs for ${group_version} at ${gv_dir}"
{
echo -e "$(cat boilerplate.generatego.txt)\n"
echo "package ${group_version##*/}"
cat <<EOF
// This file contains a collection of methods that can be used from go-restful 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:...) if and only if
// they 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. DO NOT EDIT.
EOF
} > "${TMPFILE}"
go run ./swagger_type_docs.go -s \
"${gv_dir}/types.go" \
-f - \
>> "${TMPFILE}"
echo "// AUTO-GENERATED FUNCTIONS END HERE" >> "${TMPFILE}"
gofmt -w -s "${TMPFILE}"
mv "${TMPFILE}" "${gv_dir}/types_swagger_doc_generated.go"
}
pkg/apis/core/v1/tool/swagger_type_docs.go
-75
View File
@@ -1,75 +0,0 @@
/*
Copyright 2015 The Kubernetes Authors.
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.
*/
//
// Please refer https://github.com/kubernetes/kubernetes/blob/master/cmd/genswaggertypedocs/swagger_type_docs.go for original file
//
package main
import (
"fmt"
"io"
"os"
kruntime "k8s.io/apimachinery/pkg/runtime"
flag "github.com/spf13/pflag"
"k8s.io/klog"
)
var (
functionDest = flag.StringP("func-dest", "f", "-", "Output for swagger functions; '-' means stdout (default)")
typeSrc = flag.StringP("type-src", "s", "", "From where we are going to read the types")
verify = flag.BoolP("verify", "v", false, "Verifies if the given type-src file has documentation for every type")
)
func main() {
flag.Parse()
if *typeSrc == "" {
klog.Fatalf("Please define -s flag as it is the source file")
}
var funcOut io.Writer
if *functionDest == "-" {
funcOut = os.Stdout
} else {
file, err := os.Create(*functionDest)
if err != nil {
klog.Fatalf("Couldn't open %v: %v", *functionDest, err)
}
defer file.Close()
funcOut = file
}
docsForTypes := kruntime.ParseDocumentationFrom(*typeSrc)
if *verify {
rc, err := kruntime.VerifySwaggerDocsExist(docsForTypes, funcOut)
if err != nil {
fmt.Fprintf(os.Stderr, "Error in verification process: %s\n", err)
}
os.Exit(rc)
}
if len(docsForTypes) > 0 {
if err := kruntime.WriteSwaggerDocFunc(docsForTypes, funcOut); err != nil {
fmt.Fprintf(os.Stderr, "Error when writing swagger documentation functions: %s\n", err)
os.Exit(-1)
}
}
}
pkg/apis/core/v1/tool/update-generated-swagger-docs.sh
-39
View File
@@ -1,39 +0,0 @@
#!/usr/bin/env bash
# Copyright 2015 The Kubernetes Authors.
#
# 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.
# Generates `types_swagger_doc_generated.go` files for API group
# versions. That file contains functions on API structs that return
# the comments that should be surfaced for the corresponding API type
# in our API docs.
#
# Please refer https://github.com/kubernetes/kubernetes/tree/master/hack for original file
#
set -o errexit
set -o nounset
set -o pipefail
FISSION_CRD_VERSION=v1
source "swagger.sh"
# To avoid compile errors, remove the currently existing files.
for group_version in "${FISSION_CRD_VERSION}"; do
kube::swagger::gen_types_swagger_doc "${group_version}" ../../${FISSION_CRD_VERSION}
done
pkg/apis/core/v1/types_swagger_doc_generated.go → pkg/apis/core/v1/zz_generated.swagger_doc_generated.go
+3 -5
View File
@@ -1,5 +1,5 @@
/*
Copyright 2019 The Fission Authors.
Copyright The Fission Authors.
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
@@ -13,7 +13,6 @@ 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.
*/
package v1
// This file contains a collection of methods that can be used from go-restful to
@@ -24,9 +23,8 @@ package v1
// they 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. DO NOT EDIT.
// Those methods can be generated by using hack/update-swagger-docs.sh
// AUTO-GENERATED FUNCTIONS START HERE
var map_Archive = map[string]string{
"": "Archive contains or references a collection of source or binary files.",
"type": "Type defines how the package is specified: literal or URL. Available value:\n - literal\n - url",