Generate API documents for Karmada CRD

Signed-off-by: lonelyCZ <531187475@qq.com>
This commit is contained in:
lonelyCZ 2022-03-08 19:51:05 +08:00
parent fd1a7689b6
commit 4770322945
5 changed files with 17066 additions and 0 deletions

16621
api/openapi-spec/swagger.json Normal file

File diff suppressed because it is too large Load Diff

View File

@ -0,0 +1,106 @@
package main
import (
"fmt"
"k8s.io/apimachinery/pkg/api/meta"
"k8s.io/apimachinery/pkg/runtime/serializer"
"k8s.io/klog/v2"
"k8s.io/kube-openapi/pkg/common"
"k8s.io/kube-openapi/pkg/validation/spec"
"github.com/karmada-io/karmada/hack/tools/swagger/lib"
clusterv1alpha1 "github.com/karmada-io/karmada/pkg/apis/cluster/v1alpha1"
configv1alpha1 "github.com/karmada-io/karmada/pkg/apis/config/v1alpha1"
networkingv1alpha1 "github.com/karmada-io/karmada/pkg/apis/networking/v1alpha1"
policyv1alpha1 "github.com/karmada-io/karmada/pkg/apis/policy/v1alpha1"
workv1alpha1 "github.com/karmada-io/karmada/pkg/apis/work/v1alpha1"
workv1alpha2 "github.com/karmada-io/karmada/pkg/apis/work/v1alpha2"
generatedopenapi "github.com/karmada-io/karmada/pkg/generated/openapi"
"github.com/karmada-io/karmada/pkg/util/gclient"
)
func main() {
Scheme := gclient.NewSchema()
mapper := meta.NewDefaultRESTMapper(nil)
mapper.AddSpecific(clusterv1alpha1.SchemeGroupVersion.WithKind(clusterv1alpha1.ResourceKindCluster),
clusterv1alpha1.SchemeGroupVersion.WithResource(clusterv1alpha1.ResourcePluralCluster),
clusterv1alpha1.SchemeGroupVersion.WithResource(clusterv1alpha1.ResourceSingularCluster), meta.RESTScopeRoot)
mapper.AddSpecific(configv1alpha1.SchemeGroupVersion.WithKind(configv1alpha1.ResourceKindResourceInterpreterWebhookConfiguration),
configv1alpha1.SchemeGroupVersion.WithResource(configv1alpha1.ResourcePluralResourceInterpreterWebhookConfiguration),
configv1alpha1.SchemeGroupVersion.WithResource(configv1alpha1.ResourceSingularResourceInterpreterWebhookConfiguration), meta.RESTScopeRoot)
mapper.AddSpecific(networkingv1alpha1.SchemeGroupVersion.WithKind(networkingv1alpha1.ResourceKindMultiClusterIngress),
networkingv1alpha1.SchemeGroupVersion.WithResource(networkingv1alpha1.ResourcePluralMultiClusterIngress),
networkingv1alpha1.SchemeGroupVersion.WithResource(networkingv1alpha1.ResourceSingularMultiClusterIngress), meta.RESTScopeRoot)
mapper.AddSpecific(policyv1alpha1.SchemeGroupVersion.WithKind(policyv1alpha1.ResourceKindPropagationPolicy),
policyv1alpha1.SchemeGroupVersion.WithResource(policyv1alpha1.ResourcePluralPropagationPolicy),
policyv1alpha1.SchemeGroupVersion.WithResource(policyv1alpha1.ResourceSingularPropagationPolicy), meta.RESTScopeRoot)
mapper.AddSpecific(policyv1alpha1.SchemeGroupVersion.WithKind(policyv1alpha1.ResourceKindClusterPropagationPolicy),
policyv1alpha1.SchemeGroupVersion.WithResource(policyv1alpha1.ResourcePluralClusterPropagationPolicy),
policyv1alpha1.SchemeGroupVersion.WithResource(policyv1alpha1.ResourceSingularClusterPropagationPolicy), meta.RESTScopeRoot)
mapper.AddSpecific(policyv1alpha1.SchemeGroupVersion.WithKind(policyv1alpha1.ResourceKindOverridePolicy),
policyv1alpha1.SchemeGroupVersion.WithResource(policyv1alpha1.ResourcePluralOverridePolicy),
policyv1alpha1.SchemeGroupVersion.WithResource(policyv1alpha1.ResourceSingularOverridePolicy), meta.RESTScopeRoot)
mapper.AddSpecific(policyv1alpha1.SchemeGroupVersion.WithKind(policyv1alpha1.ResourceKindClusterOverridePolicy),
policyv1alpha1.SchemeGroupVersion.WithResource(policyv1alpha1.ResourcePluralClusterOverridePolicy),
policyv1alpha1.SchemeGroupVersion.WithResource(policyv1alpha1.ResourceSingularClusterOverridePolicy), meta.RESTScopeRoot)
mapper.AddSpecific(policyv1alpha1.SchemeGroupVersion.WithKind(policyv1alpha1.ResourceKindFederatedResourceQuota),
policyv1alpha1.SchemeGroupVersion.WithResource(policyv1alpha1.ResourcePluralFederatedResourceQuota),
policyv1alpha1.SchemeGroupVersion.WithResource(policyv1alpha1.ResourceSingularFederatedResourceQuota), meta.RESTScopeRoot)
mapper.AddSpecific(workv1alpha1.SchemeGroupVersion.WithKind(workv1alpha1.ResourceKindWork),
workv1alpha1.SchemeGroupVersion.WithResource(workv1alpha1.ResourcePluralWork),
workv1alpha1.SchemeGroupVersion.WithResource(workv1alpha1.ResourceSingularWork), meta.RESTScopeRoot)
mapper.AddSpecific(workv1alpha2.SchemeGroupVersion.WithKind(workv1alpha2.ResourceKindResourceBinding),
workv1alpha2.SchemeGroupVersion.WithResource(workv1alpha2.ResourcePluralResourceBinding),
workv1alpha2.SchemeGroupVersion.WithResource(workv1alpha2.ResourceSingularResourceBinding), meta.RESTScopeRoot)
mapper.AddSpecific(workv1alpha2.SchemeGroupVersion.WithKind(workv1alpha2.ResourceKindClusterResourceBinding),
workv1alpha2.SchemeGroupVersion.WithResource(workv1alpha2.ResourcePluralClusterResourceBinding),
workv1alpha2.SchemeGroupVersion.WithResource(workv1alpha2.ResourceSingularClusterResourceBinding), meta.RESTScopeRoot)
spec, err := lib.RenderOpenAPISpec(lib.Config{
Info: spec.InfoProps{
Title: "Karmada OpenAPI",
Version: "unversioned",
Description: "Karmada is Open, Multi-Cloud, Multi-Cluster Kubernetes Orchestration System. For more information, please see https://github.com/karmada-io/karmada.",
License: &spec.License{
Name: "Apache 2.0",
URL: "https://www.apache.org/licenses/LICENSE-2.0.html",
},
},
Scheme: Scheme,
Codecs: serializer.NewCodecFactory(Scheme),
OpenAPIDefinitions: []common.GetOpenAPIDefinitions{
generatedopenapi.GetOpenAPIDefinitions,
},
Resources: []lib.ResourceWithNamespaceScoped{
{GVR: clusterv1alpha1.SchemeGroupVersion.WithResource(clusterv1alpha1.ResourcePluralCluster), NamespaceScoped: clusterv1alpha1.ResourceNamespaceScopedCluster},
{GVR: configv1alpha1.SchemeGroupVersion.WithResource(configv1alpha1.ResourcePluralResourceInterpreterWebhookConfiguration), NamespaceScoped: configv1alpha1.ResourceNamespaceScopedResourceInterpreterWebhookConfiguration},
{GVR: networkingv1alpha1.SchemeGroupVersion.WithResource(networkingv1alpha1.ResourcePluralMultiClusterIngress), NamespaceScoped: networkingv1alpha1.ResourceNamespaceScopedMultiClusterIngress},
{GVR: policyv1alpha1.SchemeGroupVersion.WithResource(policyv1alpha1.ResourcePluralPropagationPolicy), NamespaceScoped: policyv1alpha1.ResourceNamespaceScopedPropagationPolicy},
{GVR: policyv1alpha1.SchemeGroupVersion.WithResource(policyv1alpha1.ResourcePluralClusterPropagationPolicy), NamespaceScoped: policyv1alpha1.ResourceNamespaceScopedClusterPropagationPolicy},
{GVR: policyv1alpha1.SchemeGroupVersion.WithResource(policyv1alpha1.ResourcePluralOverridePolicy), NamespaceScoped: policyv1alpha1.ResourceNamespaceScopedOverridePolicy},
{GVR: policyv1alpha1.SchemeGroupVersion.WithResource(policyv1alpha1.ResourcePluralClusterOverridePolicy), NamespaceScoped: policyv1alpha1.ResourceNamespaceScopedClusterOverridePolicy},
{GVR: policyv1alpha1.SchemeGroupVersion.WithResource(policyv1alpha1.ResourcePluralFederatedResourceQuota), NamespaceScoped: policyv1alpha1.ResourceNamespaceScopedFederatedResourceQuota},
{GVR: workv1alpha1.SchemeGroupVersion.WithResource(workv1alpha1.ResourcePluralWork), NamespaceScoped: workv1alpha1.ResourceNamespaceScopedWork},
{GVR: workv1alpha2.SchemeGroupVersion.WithResource(workv1alpha2.ResourcePluralResourceBinding), NamespaceScoped: workv1alpha2.ResourceNamespaceScopedResourceBinding},
{GVR: workv1alpha2.SchemeGroupVersion.WithResource(workv1alpha2.ResourcePluralClusterResourceBinding), NamespaceScoped: workv1alpha2.ResourceNamespaceScopedClusterResourceBinding},
},
Mapper: mapper,
})
if err != nil {
klog.Fatal(err.Error())
}
fmt.Println(spec)
}

View File

@ -0,0 +1,171 @@
package lib
import (
"encoding/json"
"fmt"
"net"
"k8s.io/apimachinery/pkg/api/meta"
metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
"k8s.io/apimachinery/pkg/runtime"
"k8s.io/apimachinery/pkg/runtime/schema"
"k8s.io/apimachinery/pkg/runtime/serializer"
"k8s.io/apiserver/pkg/endpoints/openapi"
"k8s.io/apiserver/pkg/registry/rest"
genericapiserver "k8s.io/apiserver/pkg/server"
genericoptions "k8s.io/apiserver/pkg/server/options"
"k8s.io/klog/v2"
"k8s.io/kube-openapi/pkg/builder"
"k8s.io/kube-openapi/pkg/common"
"k8s.io/kube-openapi/pkg/validation/spec"
)
// ResourceWithNamespaceScoped contain gvr and NamespaceScoped of a resource.
type ResourceWithNamespaceScoped struct {
GVR schema.GroupVersionResource
NamespaceScoped bool
}
// Config is used to configure swagger information.
type Config struct {
Scheme *runtime.Scheme
Codecs serializer.CodecFactory
Info spec.InfoProps
OpenAPIDefinitions []common.GetOpenAPIDefinitions
Resources []ResourceWithNamespaceScoped
Mapper *meta.DefaultRESTMapper
}
// GetOpenAPIDefinitions get openapi definitions.
func (c *Config) GetOpenAPIDefinitions(ref common.ReferenceCallback) map[string]common.OpenAPIDefinition {
out := map[string]common.OpenAPIDefinition{}
for _, def := range c.OpenAPIDefinitions {
for k, v := range def(ref) {
out[k] = v
}
}
return out
}
// RenderOpenAPISpec create openapi spec of swagger.
func RenderOpenAPISpec(cfg Config) (string, error) {
options := genericoptions.NewRecommendedOptions("/registry/karmada.io", cfg.Codecs.LegacyCodec())
options.SecureServing.ServerCert.CertDirectory = "/tmp/karmada-swagger"
options.SecureServing.BindPort = 6445
options.Etcd = nil
options.Authentication = nil
options.Authorization = nil
options.CoreAPI = nil
options.Admission = nil
if err := options.SecureServing.MaybeDefaultWithSelfSignedCerts("localhost", nil, []net.IP{net.ParseIP("127.0.0.1")}); err != nil {
klog.Fatal(fmt.Errorf("error creating self-signed certificates: %v", err))
}
serverConfig := genericapiserver.NewRecommendedConfig(cfg.Codecs)
if err := options.ApplyTo(serverConfig); err != nil {
klog.Fatal(err)
return "", err
}
serverConfig.OpenAPIConfig = genericapiserver.DefaultOpenAPIConfig(cfg.GetOpenAPIDefinitions, openapi.NewDefinitionNamer(cfg.Scheme))
serverConfig.OpenAPIConfig.Info.InfoProps = cfg.Info
genericServer, err := serverConfig.Complete().New("karmada-openapi-server", genericapiserver.NewEmptyDelegate())
if err != nil {
klog.Fatal(err)
return "", err
}
table, err := createRouterTable(&cfg)
if err != nil {
klog.Fatal(err)
return "", err
}
for g, resmap := range table {
apiGroupInfo := genericapiserver.NewDefaultAPIGroupInfo(g, cfg.Scheme, metav1.ParameterCodec, cfg.Codecs)
storage := map[string]map[string]rest.Storage{}
for r, info := range resmap {
if storage[info.gvk.Version] == nil {
storage[info.gvk.Version] = map[string]rest.Storage{}
}
storage[info.gvk.Version][r.Resource] = &StandardREST{info}
// Add status router for all resources.
storage[info.gvk.Version][r.Resource+"/status"] = &StatusREST{StatusInfo{
gvk: info.gvk,
obj: info.obj,
}}
// To define additional endpoints for CRD resources, we need to
// implement our own REST interface and add it to our custom path.
if r.Resource == "clusters" {
storage[info.gvk.Version][r.Resource+"/proxy"] = &ProxyREST{}
}
}
for version, s := range storage {
apiGroupInfo.VersionedResourcesStorageMap[version] = s
}
// Install api to apiserver.
if err := genericServer.InstallAPIGroup(&apiGroupInfo); err != nil {
klog.Fatal(err)
return "", err
}
}
// Create Swagger Spec.
spec, err := builder.BuildOpenAPISpec(genericServer.Handler.GoRestfulContainer.RegisteredWebServices(), serverConfig.OpenAPIConfig)
if err != nil {
klog.Fatal(err)
return "", err
}
data, err := json.MarshalIndent(spec, "", " ")
if err != nil {
klog.Fatal(err)
return "", err
}
return string(data), nil
}
// createRouterTable create router map for every resource.
func createRouterTable(cfg *Config) (map[string]map[schema.GroupVersionResource]ResourceInfo, error) {
table := map[string]map[schema.GroupVersionResource]ResourceInfo{}
// Create router map for every resource
for _, ti := range cfg.Resources {
var resmap map[schema.GroupVersionResource]ResourceInfo
if m, found := table[ti.GVR.Group]; found {
resmap = m
} else {
resmap = map[schema.GroupVersionResource]ResourceInfo{}
table[ti.GVR.Group] = resmap
}
gvk, err := cfg.Mapper.KindFor(ti.GVR)
if err != nil {
klog.Fatal(err)
return nil, err
}
obj, err := cfg.Scheme.New(gvk)
if err != nil {
klog.Fatal(err)
return nil, err
}
list, err := cfg.Scheme.New(gvk.GroupVersion().WithKind(gvk.Kind + "List"))
if err != nil {
klog.Fatal(err)
return nil, err
}
resmap[ti.GVR] = ResourceInfo{
gvk: gvk,
obj: obj,
list: list,
namespaceScoped: ti.NamespaceScoped,
}
}
return table, nil
}

View File

@ -0,0 +1,153 @@
package lib
import (
"context"
"net/http"
metainternalversion "k8s.io/apimachinery/pkg/apis/meta/internalversion"
metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
"k8s.io/apimachinery/pkg/runtime"
"k8s.io/apimachinery/pkg/runtime/schema"
"k8s.io/apimachinery/pkg/watch"
"k8s.io/apiserver/pkg/registry/rest"
clusterv1alpha1 "github.com/karmada-io/karmada/pkg/apis/cluster/v1alpha1"
)
// StandardREST define CRUD api for resources.
type StandardREST struct {
cfg ResourceInfo
}
// StatusREST define status endpoint for resources.
type StatusREST struct {
cfg StatusInfo
}
// ProxyREST define proxy endpoint for resources.
type ProxyREST struct{}
// Implement below interfaces for StandardREST.
var _ rest.GroupVersionKindProvider = &StandardREST{}
var _ rest.Scoper = &StandardREST{}
var _ rest.StandardStorage = &StandardREST{}
// Implement below interfaces for StatusREST.
var _ rest.Patcher = &StatusREST{}
// Implement below interfaces for ProxyREST.
var _ rest.Connecter = &ProxyREST{}
// GroupVersionKind implement GroupVersionKind interface.
func (r *StandardREST) GroupVersionKind(containingGV schema.GroupVersion) schema.GroupVersionKind {
return r.cfg.gvk
}
// NamespaceScoped implement NamespaceScoped interface.
func (r *StandardREST) NamespaceScoped() bool {
return r.cfg.namespaceScoped
}
// New implement New interface.
func (r *StandardREST) New() runtime.Object {
return r.cfg.obj
}
// Create implement Create interface.
func (r *StandardREST) Create(ctx context.Context, obj runtime.Object, createValidation rest.ValidateObjectFunc, options *metav1.CreateOptions) (runtime.Object, error) {
return r.New(), nil
}
// Get implement Get interface.
func (r *StandardREST) Get(ctx context.Context, name string, options *metav1.GetOptions) (runtime.Object, error) {
return r.New(), nil
}
// NewList implement NewList interface.
func (r *StandardREST) NewList() runtime.Object {
return r.cfg.list
}
// List implement List interface.
func (r *StandardREST) List(ctx context.Context, options *metainternalversion.ListOptions) (runtime.Object, error) {
return r.NewList(), nil
}
// ConvertToTable implement ConvertToTable interface.
func (r *StandardREST) ConvertToTable(ctx context.Context, object runtime.Object, tableOptions runtime.Object) (*metav1.Table, error) {
return nil, nil
}
// Update implement Update interface.
func (r *StandardREST) Update(ctx context.Context, name string, objInfo rest.UpdatedObjectInfo, createValidation rest.ValidateObjectFunc, updateValidation rest.ValidateObjectUpdateFunc, forceAllowCreate bool, options *metav1.UpdateOptions) (runtime.Object, bool, error) {
return r.New(), true, nil
}
// Delete implement Delete interface.
func (r *StandardREST) Delete(ctx context.Context, name string, deleteValidation rest.ValidateObjectFunc, options *metav1.DeleteOptions) (runtime.Object, bool, error) {
return r.New(), true, nil
}
// DeleteCollection implement DeleteCollection interface.
func (r *StandardREST) DeleteCollection(ctx context.Context, deleteValidation rest.ValidateObjectFunc, options *metav1.DeleteOptions, listOptions *metainternalversion.ListOptions) (runtime.Object, error) {
return r.NewList(), nil
}
// Watch implement Watch interface.
func (r *StandardREST) Watch(ctx context.Context, options *metainternalversion.ListOptions) (watch.Interface, error) {
return nil, nil
}
// GroupVersionKind implement GroupVersionKind interface.
func (r *StatusREST) GroupVersionKind(containingGV schema.GroupVersion) schema.GroupVersionKind {
return r.cfg.gvk
}
// New returns Cluster object.
func (r *StatusREST) New() runtime.Object {
return r.cfg.obj
}
// Update alters the status subset of an object.
func (r *StatusREST) Update(ctx context.Context, name string, objInfo rest.UpdatedObjectInfo, createValidation rest.ValidateObjectFunc, updateValidation rest.ValidateObjectUpdateFunc, forceAllowCreate bool, options *metav1.UpdateOptions) (runtime.Object, bool, error) {
return r.New(), true, nil
}
// Get retrieves the status object.
func (r *StatusREST) Get(ctx context.Context, name string, options *metav1.GetOptions) (runtime.Object, error) {
return r.New(), nil
}
// New returns an empty cluster proxy subresource.
func (r *ProxyREST) New() runtime.Object {
return &clusterv1alpha1.ClusterProxyOptions{}
}
// ConnectMethods returns the list of HTTP methods handled by Connect.
func (r *ProxyREST) ConnectMethods() []string {
return []string{"GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"}
}
// NewConnectOptions returns versioned resource that represents proxy parameters.
func (r *ProxyREST) NewConnectOptions() (runtime.Object, bool, string) {
return &clusterv1alpha1.ClusterProxyOptions{}, true, "path"
}
// Connect implement Connect interface.
func (r *ProxyREST) Connect(ctx context.Context, id string, options runtime.Object, responder rest.Responder) (http.Handler, error) {
return nil, nil
}
// ResourceInfo is content of StandardREST.
type ResourceInfo struct {
gvk schema.GroupVersionKind
obj runtime.Object
list runtime.Object
namespaceScoped bool
}
// StatusInfo is content of StatusREST.
type StatusInfo struct {
gvk schema.GroupVersionKind
obj runtime.Object
}

15
hack/update-swagger-docs.sh Executable file
View File

@ -0,0 +1,15 @@
#!/usr/bin/env bash
set -o errexit
set -o nounset
set -o pipefail
REPO_ROOT=$(dirname "${BASH_SOURCE[0]}")/..
source "${REPO_ROOT}"/hack/util.sh
util::verify_go_version
go run hack/tools/swagger/generateswagger.go > api/openapi-spec/swagger.json
# Delete trash of generating swagger doc
rm -rf /tmp/karmada-swagger