Merge pull request #10933 from andronat/swagger_auto_type_docs

Automatic Generation of Swagger Documentation in Types

cmd/genswaggertypedocs/swagger_type_docs.go

@@ -0,0 +1,73 @@
+/*
+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.
+*/
+
+package main
+
+import (
+	"fmt"
+	"io"
+	"os"
+	"runtime"
+
+	pkg_runtime "k8s.io/kubernetes/pkg/runtime"
+
+	"github.com/golang/glog"
+	flag "github.com/spf13/pflag"
+)
+
+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() {
+	runtime.GOMAXPROCS(runtime.NumCPU())
+	flag.Parse()
+
+	if *typeSrc == "" {
+		glog.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 {
+			glog.Fatalf("Couldn't open %v: %v", *functionDest, err)
+		}
+		defer file.Close()
+		funcOut = file
+	}
+
+	docsForTypes := pkg_runtime.ParseDocumentationFrom(*typeSrc)
+
+	if *verify == true {
+		rc, err := pkg_runtime.VerifySwaggerDocsExist(docsForTypes, funcOut)
+		if err != nil {
+			fmt.Fprintf(os.Stderr, "Error in verification process: %s\n", err)
+		}
+		os.Exit(rc)
+	}
+
+	if docsForTypes != nil && len(docsForTypes) > 0 {
+		if err := pkg_runtime.WriteSwaggerDocFunc(docsForTypes, funcOut); err != nil {
+			fmt.Fprintf(os.Stderr, "Error when writing swagger documentation functions: %s\n", err)
+			os.Exit(-1)
+		}
+	}
+}