ahmetb/gen-crd-api-reference-docs

# Kubernetes Custom Resource API 参考文档生成器 如果你的项目提供了 Custom Resource Definitions 并且想要生成 像[这样][ar]的 API 参考文档，那么这款工具就是为你准备的。 ## 替代方案 本项目启发了以下项目的创建： - [**Kubernetes reference-docs generator**](https://github.com/kubernetes-sigs/reference-docs)： 用于[官方 Kubernetes 组件参考文档](https://kubernetes.io/docs/reference/config-api/kubelet-config.v1beta1/) - 由 Elastic 提供的 [**crd-ref-docs**](https://github.com/elastic/crd-ref-docs)：本项目的一个全新实现。 - 如果你是一个开源项目，可以考虑通过 https://doc.crds.dev/ 毫不费力地公开你的 CRD API 参考。 ## 当前用户 - [**Knative** API 参考文档](https://knative.dev/docs/reference/api/serving-api/) - [**FluxCD** API 参考文档](https://fluxcd.io/docs/components/source/api/) - [**Argo CD** operator API 参考文档](https://argocd-operator.readthedocs.io/en/latest/reference/api.html/) - [**Contour** ingress controller API 参考文档](https://projectcontour.io/docs/v1.19.0/config/api/) - [**Kubeflow** API 参考文档](https://www.kubeflow.org/docs/reference/overview/) - [**cert-manager** API 参考文档](https://cert-manager.io/docs/reference/api-docs/) - [**Open Service Mesh** API 参考文档](https://release-v0-11.docs.openservicemesh.io/docs/api_reference/config/v1alpha1/) - [**PlanetScale Vitess Operator** API 参考文档](https://github.com/planetscale/vitess-operator/blob/main/docs/api.md) - [**Agones** API 参考文档](https://agones.dev/site/docs/reference/agones_crd_api_reference/) - [**Gardener** API 参考文档](https://gardener.cloud/api-reference/) - [**New Relic Alert Manager** API 参考文档](https://github.com/fpetkovski/newrelic-alert-manager/tree/master/docs) - [**Antrea** API 参考文档](https://antrea.io/docs/v1.3.0/docs/api-reference/) - [**kube-green** API 参考文档](https://kube-green.dev/docs/apireference_v1alpha1/) - [**Azure Service Operator** 支持的资源](https://azure.github.io/azure-service-operator/reference/) - [**NGINX Gateway Fabric** API 参考文档](https://docs.nginx.com/nginx-gateway-fabric/reference/api/) - _[[在此添加你的项目]]_ 还有一些 **fork**： - [**elastic/crd-ref-docs**](https://github.com/elastic/crd-ref-docs)：受本项目启发的全新重新实现，支持 AsciiDoc。被 Elastic Cloud on Kubernetes API 参考文档使用。 ## 为什么 通常你会想使用与 [Kubernetes API 参考][ar]相同的[文档生成器][dg]，但以下是我编写了一个不同的解析器/生成器的原因： 1. 目前，Kubernetes API [并未][pr]为 CRD（例如 Knative）提供 OpenAPI 规范，因此 Kubernetes 使用的 [gen-apidocs][ga] 生成器将无法工作。 2. 即使 Kubernetes API 开始为 CRD 提供 OpenAPI 规范，你的 CRD 也必须具有验证 schema（例如 Knative API 就没有！） 3. Kubernetes [gen-apidocs][ga] 解析器依赖于运行 `kube-apiserver` 并调用 `/apis` endpoint 来获取 OpenAPI 规范以生成文档。**这款工具不需要这些！** ## 如何实现 这是一个自定义的 API 参考文档生成器，它使用 [k8s.io/gengo](https://godoc.org/k8s.io/gengo) 项目来解析类型并从中生成 API 文档。 此工具的功能包括： - 不依赖 OpenAPI 规范、kube-apiserver 或运行中的 cluster。 - 仅依赖 Go 源代码 (pkg/apis/**/*.go) 来解析 API 类型。 - 可以链接到外部 API 的其他站点。例如，如果你的类型引用了 Kubernetes core/v1.PodSpec，你可以链接到它。 - 支持[可配置](./example-config.json)设置，以从生成的输出中完全隐藏某些字段或类型。 - 可以输出到文件或启动实时 http-server（用于快速迭代）。 - 支持从 godoc 类型、包和字段注释渲染 markdown。 ## 试用 1. Clone 此 repository。 2. 确保你安装了 go1.11+。然后运行 `go build`，你应该会在当前目录中得到一个 `gen-crd-api-reference-docs` 二进制可执行文件。 3. Clone 一个 Knative repository，正确设置 GOPATH，并在该目录中调用编译后的二进制文件。 # 进入设置了 GOPATH 的 repository 根目录。（我使用我自己的脚本 # goclone(1) 为我 clone 的每个 repo 设置单独的 GOPATH。） $ goclone knative/build $ /path/to/gen-crd-api-reference-docs \ -config "/path/to/example-config.json" \ -api-dir "github.com/knative/build/pkg/apis/build/v1alpha1" \ -out-file docs.html 4. 访问 `docs.html` 查看结果。 这不是一个官方的 Google 项目。请参阅 [LICENSE](./LICENSE)。

标签：EVTX分析, SOC Prime, 子域名突变, 开发工具, 文档生成器, 日志审计