Generates OpenAPI (aka Swagger 2.0) Spec on /swagger.json path

cmd/kube-apiserver/app/server.go

@@ -272,6 +272,7 @@ func Run(s *options.APIServer) error {
 	genericConfig.ProxyDialer = proxyDialerFn
 	genericConfig.ProxyTLSClientConfig = proxyTLSClientConfig
 	genericConfig.Serializer = api.Codecs
+	genericConfig.OpenAPIInfo.Title = "Kubernetes"
 
 	config := &master.Config{
 		Config:                  genericConfig,

pkg/genericapiserver/genericapiserver.go

@@ -36,6 +36,7 @@ import (
 	"github.com/golang/glog"
 	"gopkg.in/natefinch/lumberjack.v2"
 
+	"github.com/go-openapi/spec"
 	"k8s.io/kubernetes/pkg/admission"
 	"k8s.io/kubernetes/pkg/api"
 	"k8s.io/kubernetes/pkg/api/rest"
@@ -48,6 +49,7 @@ import (
 	"k8s.io/kubernetes/pkg/auth/authorizer"
 	"k8s.io/kubernetes/pkg/auth/handlers"
 	"k8s.io/kubernetes/pkg/cloudprovider"
+	"k8s.io/kubernetes/pkg/genericapiserver/openapi"
 	"k8s.io/kubernetes/pkg/genericapiserver/options"
 	genericvalidation "k8s.io/kubernetes/pkg/genericapiserver/validation"
 	"k8s.io/kubernetes/pkg/registry/generic"
@@ -192,6 +194,15 @@ type Config struct {
 	ExtraEndpointPorts []api.EndpointPort
 
 	KubernetesServiceNodePort int
+
+	// EnableOpenAPISupport enables OpenAPI support. Allow downstream customers to disable OpenAPI spec.
+	EnableOpenAPISupport bool
+
+	// OpenAPIInfo will be directly available as Info section of Open API spec.
+	OpenAPIInfo spec.Info
+
+	// OpenAPIDefaultResponse will be used if an web service operation does not have any responses listed.
+	OpenAPIDefaultResponse spec.Response
 }
 
 // GenericAPIServer contains state for a Kubernetes cluster api server.
@@ -252,6 +263,12 @@ type GenericAPIServer struct {
 	// Map storing information about all groups to be exposed in discovery response.
 	// The map is from name to the group.
 	apiGroupsForDiscovery map[string]unversioned.APIGroup
+
+	// See Config.$name for documentation of these flags
+
+	enableOpenAPISupport   bool
+	openAPIInfo            spec.Info
+	openAPIDefaultResponse spec.Response
 }
 
 func (s *GenericAPIServer) StorageDecorator() generic.StorageDecorator {
@@ -378,6 +395,10 @@ func New(c *Config) (*GenericAPIServer, error) {
 
 		KubernetesServiceNodePort: c.KubernetesServiceNodePort,
 		apiGroupsForDiscovery:     map[string]unversioned.APIGroup{},
+
+		enableOpenAPISupport:   c.EnableOpenAPISupport,
+		openAPIInfo:            c.OpenAPIInfo,
+		openAPIDefaultResponse: c.OpenAPIDefaultResponse,
 	}
 
 	if c.RestfulContainer != nil {
@@ -579,6 +600,16 @@ func NewConfig(options *options.ServerRunOptions) *Config {
 		ReadWritePort:             options.SecurePort,
 		ServiceClusterIPRange:     &options.ServiceClusterIPRange,
 		ServiceNodePortRange:      options.ServiceNodePortRange,
+		EnableOpenAPISupport:      true,
+		OpenAPIDefaultResponse: spec.Response{
+			ResponseProps: spec.ResponseProps{
+				Description: "Default Response."}},
+		OpenAPIInfo: spec.Info{
+			InfoProps: spec.InfoProps{
+				Title:   "Generic API Server",
+				Version: "unversioned",
+			},
+		},
 	}
 }
 
@@ -632,6 +663,9 @@ func (s *GenericAPIServer) Run(options *options.ServerRunOptions) {
 	if s.enableSwaggerSupport {
 		s.InstallSwaggerAPI()
 	}
+	if s.enableOpenAPISupport {
+		s.InstallOpenAPI()
+	}
 	// We serve on 2 ports. See docs/admin/accessing-the-api.md
 	secureLocation := ""
 	if options.SecurePort != 0 {
@@ -868,17 +902,12 @@ func (s *GenericAPIServer) newAPIGroupVersion(apiGroupInfo *APIGroupInfo, groupV
 	}, nil
 }
 
-// InstallSwaggerAPI installs the /swaggerapi/ endpoint to allow schema discovery
-// and traversal. It is optional to allow consumers of the Kubernetes GenericAPIServer to
-// register their own web services into the Kubernetes mux prior to initialization
-// of swagger, so that other resource types show up in the documentation.
-func (s *GenericAPIServer) InstallSwaggerAPI() {
+// getSwaggerConfig returns swagger config shared between SwaggerAPI and OpenAPI spec generators
+func (s *GenericAPIServer) getSwaggerConfig() *swagger.Config {
 	hostAndPort := s.ExternalAddress
 	protocol := "https://"
 	webServicesUrl := protocol + hostAndPort
-
-	// Enable swagger UI and discovery API
-	swaggerConfig := swagger.Config{
+	return &swagger.Config{
 		WebServicesUrl:  webServicesUrl,
 		WebServices:     s.HandlerContainer.RegisteredWebServices(),
 		ApiPath:         "/swaggerapi/",
@@ -892,7 +921,30 @@ func (s *GenericAPIServer) InstallSwaggerAPI() {
 			return ""
 		},
 	}
-	swagger.RegisterSwaggerService(swaggerConfig, s.HandlerContainer)
+}
+
+// InstallSwaggerAPI installs the /swaggerapi/ endpoint to allow schema discovery
+// and traversal. It is optional to allow consumers of the Kubernetes GenericAPIServer to
+// register their own web services into the Kubernetes mux prior to initialization
+// of swagger, so that other resource types show up in the documentation.
+func (s *GenericAPIServer) InstallSwaggerAPI() {
+
+	// Enable swagger UI and discovery API
+	swagger.RegisterSwaggerService(*s.getSwaggerConfig(), s.HandlerContainer)
+}
+
+// InstallOpenAPI installs the /swagger.json endpoint to allow new OpenAPI schema discovery.
+func (s *GenericAPIServer) InstallOpenAPI() {
+	openAPIConfig := openapi.Config{
+		SwaggerConfig:   s.getSwaggerConfig(),
+		IgnorePrefixes:  []string{"/swaggerapi"},
+		Info:            &s.openAPIInfo,
+		DefaultResponse: &s.openAPIDefaultResponse,
+	}
+	err := openapi.RegisterOpenAPIService(&openAPIConfig, s.HandlerContainer)
+	if err != nil {
+		glog.Fatalf("Failed to generate open api spec: %v", err)
+	}
 }
 
 // NewDefaultAPIGroupInfo returns an APIGroupInfo stubbed with "normal" values

pkg/genericapiserver/openapi/doc.go

+/*
+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.
+*/
+
+// Package openapi contains code to generate OpenAPI discovery spec (which
+// initial version of it also known as Swagger 2.0).
+// For more details: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md
+package openapi

pkg/master/master_test.go

@@ -64,6 +64,10 @@ import (
 	utilnet "k8s.io/kubernetes/pkg/util/net"
 	"k8s.io/kubernetes/pkg/util/sets"
 
+	"github.com/go-openapi/loads"
+	"github.com/go-openapi/spec"
+	"github.com/go-openapi/strfmt"
+	"github.com/go-openapi/validate"
 	"github.com/stretchr/testify/assert"
 	"golang.org/x/net/context"
 )
@@ -1205,3 +1209,54 @@ func testThirdPartyDiscovery(t *testing.T, version string) {
 		},
 	})
 }
+
+// TestValidOpenAPISpec verifies that the open api is added
+// at the proper endpoint and the spec is valid.
+func TestValidOpenAPISpec(t *testing.T) {
+	_, etcdserver, config, assert := setUp(t)
+	defer etcdserver.Terminate(t)
+
+	config.EnableOpenAPISupport = true
+	config.OpenAPIInfo = spec.Info{
+		InfoProps: spec.InfoProps{
+			Title:   "Kubernetes",
+			Version: "unversioned",
+		},
+	}
+	master, err := New(&config)
+	if err != nil {
+		t.Fatalf("Error in bringing up the master: %v", err)
+	}
+
+	// make sure swagger.json is not registered before calling install api.
+	server := httptest.NewServer(master.HandlerContainer.ServeMux)
+	resp, err := http.Get(server.URL + "/swagger.json")
+	if !assert.NoError(err) {
+		t.Errorf("unexpected error: %v", err)
+	}
+	assert.Equal(http.StatusNotFound, resp.StatusCode)
+
+	master.InstallOpenAPI()
+	resp, err = http.Get(server.URL + "/swagger.json")
+	if !assert.NoError(err) {
+		t.Errorf("unexpected error: %v", err)
+	}
+	assert.Equal(http.StatusOK, resp.StatusCode)
+
+	// as json schema
+	var sch spec.Schema
+	if assert.NoError(decodeResponse(resp, &sch)) {
+		validator := validate.NewSchemaValidator(spec.MustLoadSwagger20Schema(), nil, "", strfmt.Default)
+		res := validator.Validate(&sch)
+		assert.NoError(res.AsError())
+	}
+
+	// Validate OpenApi spec
+	doc, err := loads.Spec(server.URL + "/swagger.json")
+	if assert.NoError(err) {
+		// TODO(mehdy): This test is timing out on jerkin but passing locally. Enable it after debugging timeout issue.
+		_ = validate.NewSpecValidator(doc.Schema(), strfmt.Default)
+		// res, _ := validator.Validate(doc)
+		// assert.NoError(res.AsError())
+	}
+}

test/integration/framework/master_utils.go

@@ -54,6 +54,7 @@ import (
 	utilnet "k8s.io/kubernetes/pkg/util/net"
 	"k8s.io/kubernetes/plugin/pkg/admission/admit"
 
+	"github.com/go-openapi/spec"
 	"github.com/pborman/uuid"
 )
 
@@ -134,6 +135,18 @@ func startMasterOrDie(masterConfig *master.Config) (*master.Master, *httptest.Se
 		masterConfig = NewMasterConfig()
 		masterConfig.EnableProfiling = true
 		masterConfig.EnableSwaggerSupport = true
+		masterConfig.EnableOpenAPISupport = true
+		masterConfig.OpenAPIInfo = spec.Info{
+			InfoProps: spec.InfoProps{
+				Title:   "Kubernetes",
+				Version: "unversioned",
+			},
+		}
+		masterConfig.OpenAPIDefaultResponse = spec.Response{
+			ResponseProps: spec.ResponseProps{
+				Description: "Default Response.",
+			},
+		}
 	}
 	m, err := master.New(masterConfig)
 	if err != nil {