Tool that supports automatically generating API documentation #5615

Catherine-monk · 2024-05-15T12:55:03Z

Introduction

Tool that supports automatically generating API documentation.

Implementation Method

Generate OpenAPI definitions using openapi-gen: The openapi-gen tool generates Go template code containing OpenAPI definitions from comment information. By adding a specific annotation +k8s:openapigen=true in the doc.go file, openapi-gen will scan all types in the package to generate OpenAPI definitions, which are stored in the zz_generated.openapi.go file.
Generate OpenAPI Specification:
Write generate-swagger.go referencing the generated OpenAPI definitions (zz_generated.openapi.go) to create the OpenAPI specification (swagger.json). The swagger.json file contains all the OpenAPI definition information of the apiserver.

Contents of generateswagger.go include:

Create a Schema object for type registration and object instantiation.
Create a REST Mapper for converting between GVR (Group Version Resource) and GVK (Group Version Kind).
Add specific mappings for various Kubeedge resources.
Set the information for the OpenAPI specification.

Usage

First, run ./apidoc/tools/generate-openapi.sh to generate the OpenAPI definitions, then execute ./apidoc/tools/update-swagger-docs.sh to generate the OpenAPI specification.

Shelley-BaoYue

Please using make verify to update the vendor/LICENSES/crds...
1 execute make verify
2 push the modified file

Shelley-BaoYue · 2024-05-25T10:06:56Z

Please using make verify to update the vendor/LICENSES/crds... 1 execute make verify 2 push the modified file

friendly remind : )

Shelley-BaoYue · 2024-06-04T07:30:01Z

apidoc/tools/generate-openapi.sh

+    --input-dirs "k8s.io/apiextensions-apiserver/pkg/apis" \
+    --input-dirs "k8s.io/kubernetes/pkg/apis" \
+    --input-dirs "k8s.io/apimachinery/pkg/version" \
+    --input-dirs "k8s.io/apimachinery/pkg/api/resource" \


we don't need to generate k8s API

Shelley-BaoYue · 2024-06-04T07:31:05Z

apidoc/tools/generate-swagger.go

+	"k8s.io/client-go/kubernetes/scheme"
+	"k8s.io/klog/v2"
+	"k8s.io/kube-openapi/pkg/common"
+	"k8s.io/kube-openapi/pkg/validation/spec"


sort the import

Shelley-BaoYue · 2024-06-04T07:47:58Z

apidoc/tools/generate-swagger.go

+		},
+		Resources: []lib.ResourceWithNamespaceScoped{
+			// Define resources and their namespace scoped and resource mapping correspondingly
+			{GVR: appsv1alpha1.SchemeGroupVersion.WithResource("edgeapplications"), NamespaceScoped: false},


edgeapplications namespaceScope should not be false. And other apis should also be checked.

Shelley-BaoYue · 2024-06-04T07:51:49Z

apidoc/tools/update-swagger-docs.sh

+  mkdir "$folder_name"
+  fi
+
+go run ${KUBEEDGE_ROOT}/apidoc/tools/generate-swagger.go > ${KUBEEDGE_ROOT}/apidoc/generated/swagger/swagger.json


Why swagger.json in this PR is empty?

Shelley-BaoYue · 2024-06-04T08:14:52Z

build/crds/apps/apps_v1alpha1_edgeapplication.yaml

 ---
 apiVersion: apiextensions.k8s.io/v1
 kind: CustomResourceDefinition
 metadata:
  annotations:
-    controller-gen.kubebuilder.io/version: v0.6.2
-  creationTimestamp: null
+    controller-gen.kubebuilder.io/version: v0.14.0


If we must upgrade controller-gen tool in this PR? If not, remove it, If so, we need another separate PR to upgrade controller-gen.

Shelley-BaoYue · 2024-06-04T08:15:52Z

hack/generate-crds.sh

@@ -136,4 +136,4 @@ function cleanup {

 :copy:to:destination

-cleanup
+#cleanup


remove this #

Shelley-BaoYue · 2024-06-04T08:17:29Z

pkg/client/clientset/versioned/typed/devices/v1beta1/devices_client.go

@@ -28,7 +28,6 @@ import (

 type DevicesV1beta1Interface interface {
 	RESTClient() rest.Interface
-	DevicesGetter


Why remove DeviceGetter?

Shelley-BaoYue · 2024-06-04T08:18:58Z

pkg/client/informers/externalversions/devices/v1beta1/interface.go

@@ -24,8 +24,6 @@ import (

 // Interface provides access to all the informers in this group version.
 type Interface interface {
-	// Devices returns a DeviceInformer.
-	Devices() DeviceInformer


why remove Device Interface?

Shelley-BaoYue · 2024-06-04T08:23:24Z

apidoc/tools/generate-openapi.sh

+if ! test -f "${GOFILE}" ; then
+    echo "Error: Go file not found." && exit 1
+fi
+OUTPUT_FILE="${KUBEEDGE_ROOT}/vendor/k8s.io/kube-openapi/cmd/openapi-gen"


using go install k8s.io/kube-openapi/cmd/openapi-gen

Signed-off-by: guolinsheng <15079795005@163.com>

kubeedge-bot · 2024-06-04T12:40:46Z

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by:
To complete the pull request process, please assign shelley-baoyue after the PR has been reviewed.
You can assign the PR to them by writing /assign @shelley-baoyue in a comment when ready.

The full list of commands accepted by this bot can be found here.

Needs approval from an approver in each of these files:

OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

kubeedge-bot · 2024-06-04T12:40:46Z

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by:
To complete the pull request process, please assign shelley-baoyue after the PR has been reviewed.
You can assign the PR to them by writing /assign @shelley-baoyue in a comment when ready.

The full list of commands accepted by this bot can be found here.

Needs approval from an approver in each of these files:

OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

Signed-off-by: guolinsheng <15079795005@163.com>

kubeedge-bot requested review from daixiang0 and GsssC May 15, 2024 12:55

kubeedge-bot added the size/XXL Denotes a PR that changes 1000+ lines, ignoring generated files. label May 15, 2024

Shelley-BaoYue reviewed May 22, 2024

View reviewed changes

Catherine-monk closed this May 29, 2024

Catherine-monk force-pushed the master branch from 8a8b095 to 77891f2 Compare May 29, 2024 13:09

kubeedge-bot added size/XS Denotes a PR that changes 0-9 lines, ignoring generated files. and removed size/XXL Denotes a PR that changes 1000+ lines, ignoring generated files. labels May 29, 2024

Catherine-monk reopened this May 30, 2024

kubeedge-bot added size/XXL Denotes a PR that changes 1000+ lines, ignoring generated files. and removed size/XS Denotes a PR that changes 0-9 lines, ignoring generated files. labels May 30, 2024

Shelley-BaoYue reviewed Jun 4, 2024

View reviewed changes

Catherine-monk closed this Jun 4, 2024

Catherine-monk force-pushed the master branch from 44cbb13 to 135e7b3 Compare June 4, 2024 11:12

kubeedge-bot added size/XS Denotes a PR that changes 0-9 lines, ignoring generated files. and removed size/XXL Denotes a PR that changes 1000+ lines, ignoring generated files. labels Jun 4, 2024

greensong added 2 commits June 4, 2024 20:38

add openapi-gen note

7a26aed

Signed-off-by: guolinsheng <15079795005@163.com>

openapi docs

602ca36

Signed-off-by: guolinsheng <15079795005@163.com>

Catherine-monk reopened this Jun 4, 2024

kubeedge-bot added size/S Denotes a PR that changes 10-29 lines, ignoring generated files. and removed size/XS Denotes a PR that changes 0-9 lines, ignoring generated files. labels Jun 4, 2024

openapi docs

60c0683

Signed-off-by: guolinsheng <15079795005@163.com>

kubeedge-bot removed the size/S Denotes a PR that changes 10-29 lines, ignoring generated files. label Jun 4, 2024

kubeedge-bot added the size/XXL Denotes a PR that changes 1000+ lines, ignoring generated files. label Jun 4, 2024

openapi docs

a49cc41

Signed-off-by: guolinsheng <15079795005@163.com>

Shelley-BaoYue added this to the v1.18 milestone Jun 6, 2024

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Tool that supports automatically generating API documentation #5615

Tool that supports automatically generating API documentation #5615

Catherine-monk commented May 15, 2024

Shelley-BaoYue left a comment •

edited

Shelley-BaoYue commented May 25, 2024

Shelley-BaoYue Jun 4, 2024

Shelley-BaoYue Jun 4, 2024

Shelley-BaoYue Jun 4, 2024

Shelley-BaoYue Jun 4, 2024

Shelley-BaoYue Jun 4, 2024

Shelley-BaoYue Jun 4, 2024

Shelley-BaoYue Jun 4, 2024

Shelley-BaoYue Jun 4, 2024

Shelley-BaoYue Jun 4, 2024

kubeedge-bot commented Jun 4, 2024

kubeedge-bot commented Jun 4, 2024

Tool that supports automatically generating API documentation #5615

Are you sure you want to change the base?

Tool that supports automatically generating API documentation #5615

Conversation

Catherine-monk commented May 15, 2024

Introduction

Implementation Method

Usage

Shelley-BaoYue left a comment • edited

Choose a reason for hiding this comment

Shelley-BaoYue commented May 25, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

kubeedge-bot commented Jun 4, 2024

kubeedge-bot commented Jun 4, 2024

Shelley-BaoYue left a comment •

edited