Tool that supports automatically generating API documentation

Catherine-monk commented 1 month ago

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 commented 1 month ago

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

friendly remind : )

kubeedge-bot commented 3 weeks ago

[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](https://github.com/kubeedge/kubeedge/blob/master/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 commented 3 weeks ago

[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](https://github.com/kubeedge/kubeedge/blob/master/OWNERS)** Approvers can indicate their approval by writing `/approve` in a comment Approvers can cancel approval by writing `/approve cancel` in a comment

kubeedge / kubeedge