{"id":13451556,"url":"https://github.com/ahmetb/gen-crd-api-reference-docs","last_synced_at":"2025-05-15T07:03:48.495Z","repository":{"id":37736205,"uuid":"163209298","full_name":"ahmetb/gen-crd-api-reference-docs","owner":"ahmetb","description":"API Reference Docs generator for Kubernetes CRDs (used by Knative, Kubeflow and others)","archived":false,"fork":false,"pushed_at":"2025-05-12T20:15:58.000Z","size":132,"stargazers_count":319,"open_issues_count":19,"forks_count":100,"subscribers_count":6,"default_branch":"master","last_synced_at":"2025-05-15T07:03:05.807Z","etag":null,"topics":["crd","crds","kubebuilder","kubernetes-api","operator-sdk"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ahmetb.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2018-12-26T19:02:58.000Z","updated_at":"2025-05-14T12:21:33.000Z","dependencies_parsed_at":"2024-02-14T16:46:06.714Z","dependency_job_id":"38f32996-555e-4aa9-ba87-d0d89739c391","html_url":"https://github.com/ahmetb/gen-crd-api-reference-docs","commit_stats":null,"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ahmetb%2Fgen-crd-api-reference-docs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ahmetb%2Fgen-crd-api-reference-docs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ahmetb%2Fgen-crd-api-reference-docs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ahmetb%2Fgen-crd-api-reference-docs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ahmetb","download_url":"https://codeload.github.com/ahmetb/gen-crd-api-reference-docs/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254291961,"owners_count":22046424,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["crd","crds","kubebuilder","kubernetes-api","operator-sdk"],"created_at":"2024-07-31T07:00:55.785Z","updated_at":"2025-05-15T07:03:48.468Z","avatar_url":"https://github.com/ahmetb.png","language":"Go","funding_links":[],"categories":["Go"],"sub_categories":[],"readme":"# Kubernetes Custom Resource API Reference Docs generator\n\nIf you have a project that is providing Custom Resource Definitions and wanted to generate\nAPI Reference Docs [like this][ar] this tool is for you.\n\n[ar]: https://knative.dev/docs/reference/api/serving-api/\n\n## Alternatives\n\nThis project has inspired creation of the following projects:\n\n- [**Kubernetes reference-docs generator**](https://github.com/kubernetes-sigs/reference-docs):\n  used in [official Kubernetes component reference docs](https://kubernetes.io/docs/reference/config-api/kubelet-config.v1beta1/)\n\n- [**crd-ref-docs** by Elastic](https://github.com/elastic/crd-ref-docs): A fresh implementation\n  of this project.\n\nNowadays, I don't have a lot of time to maintain this tool. So consider\nusing one of the above in case this repo does not work for you. \n\nIf you're an open source project, consider exposing your\nCRD API Reference via https://doc.crds.dev/ without much effort.\n\n\n## Current Users\n\n- [**Knative** API reference docs](https://knative.dev/docs/reference/api/serving-api/)\n- [**FluxCD** API reference docs](https://fluxcd.io/docs/components/source/api/)\n- [**Argo CD** operator API reference docs](https://argocd-operator.readthedocs.io/en/latest/reference/api.html/)\n- [**Contour** ingress controller API reference docs](https://projectcontour.io/docs/v1.19.0/config/api/)\n- [**Kubeflow** API reference docs](https://www.kubeflow.org/docs/reference/overview/)\n- [**cert-manager** API reference docs](https://cert-manager.io/docs/reference/api-docs/)\n- [**Open Service Mesh** API reference docs](https://release-v0-11.docs.openservicemesh.io/docs/api_reference/config/v1alpha1/)\n- [**PlanetScale Vitess Operator** API reference docs](https://github.com/planetscale/vitess-operator/blob/main/docs/api.md)\n- [**Agones** API reference docs](https://agones.dev/site/docs/reference/agones_crd_api_reference/)\n- [**Gardener** API reference docs](https://gardener.cloud/api-reference/)\n- [**New Relic Alert Manager** API reference docs](https://github.com/fpetkovski/newrelic-alert-manager/tree/master/docs)\n- [**Antrea** API reference docs](https://antrea.io/docs/v1.3.0/docs/api-reference/)\n- [**kube-green** API reference docs](https://kube-green.dev/docs/apireference_v1alpha1/)\n- [**Azure Service Operator** supported resources](https://azure.github.io/azure-service-operator/reference/)\n- [**NGINX Gateway Fabric** API reference docs](https://docs.nginx.com/nginx-gateway-fabric/reference/api/)\n- _[[ADD YOUR PROJECT HERE]]_\n\nAlso some **forks**:\n\n- [**elastic/crd-ref-docs**](https://github.com/elastic/crd-ref-docs): A fresh re-implementation inspired\n  by this project that supports AsciiDoc. Used by Elastic Cloud on Kubernetes API reference docs.\n\n## Why\n\nNormally you would want to use the same [docs generator][dg] as [Kubernetes API\nreference][ar], but here's why I wrote a different parser/generator:\n\n1. Today, Kubernetes API [does not][pr] provide OpenAPI specs for CRDs (e.g.\n   Knative), therefore the [gen-apidocs][ga]\n   generator used by Kubernetes won't work.\n\n2. Even when Kubernetes API starts providing OpenAPI specs for CRDs, your CRD\n   must have a validation schema (e.g. Knative API doesn't!)\n\n3. Kubernetes [gen-apidocs][ga] parser relies on running a `kube-apiserver` and\n   calling `/apis` endpoint to get OpenAPI specs to generate docs. **This tool\n   doesn't need that!**\n\n[dg]: https://github.com/kubernetes-incubator/reference-docs/\n[ga]: https://github.com/kubernetes-incubator/reference-docs/tree/master/gen-apidocs/generators\n[pr]: https://github.com/kubernetes/kubernetes/pull/71192\n\n## How\n\nThis is a custom API reference docs generator that uses the\n[k8s.io/gengo](https://godoc.org/k8s.io/gengo) project to parse types and\ngenerate API documentation from it.\n\nCapabilities of this tool include:\n\n- Doesn't depend on OpenAPI specs, or kube-apiserver, or a running cluster.\n- Relies only on the Go source code (pkg/apis/**/*.go) to parse API types.\n- Can link to other sites for external APIs. For example, if your types have a\n  reference to Kubernetes core/v1.PodSpec, you can link to it.\n- [Configurable](./example-config.json) settings to hide certain fields or types\n  entirely from the generated output.\n- Either output to a file or start a live http-server (for rapid iteration).\n- Supports markdown rendering from godoc type, package and field comments.\n\n## Try it out\n\n1. Clone this repository.\n\n2. Make sure you have go1.11+ installed. Then run `go build`, you should get a\n   `gen-crd-api-reference-docs` binary executable in the current directory.\n\n3. Clone a Knative repository, set GOPATH correctly,\n   and call the compiled binary within that directory.\n\n    ```sh\n    # go into a repository root with GOPATH set. (I use my own script\n    # goclone(1) to have a separate GOPATH for each repo I clone.)\n    $ goclone knative/build\n\n    $ /path/to/gen-crd-api-reference-docs \\\n        -config \"/path/to/example-config.json\" \\\n        -api-dir \"github.com/knative/build/pkg/apis/build/v1alpha1\" \\\n        -out-file docs.html\n    ```\n\n4. Visit `docs.html` to view the results.\n\n-----\n\nThis is not an official Google project. See [LICENSE](./LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fahmetb%2Fgen-crd-api-reference-docs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fahmetb%2Fgen-crd-api-reference-docs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fahmetb%2Fgen-crd-api-reference-docs/lists"}