GoogleCloudPlatform / GoogleCloudPlatform/knowledge-catalog

Producer: convert any OpenAPI 3.x spec into an OKF v0.1 bundle

Open
#56 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
TypeScript
Stars
9.2k
Forks
782
Avg merge
6h 36m
Merged PRs (30d)
85

Description

OKF's README frames producers broadly: "export pipelines from existing catalogs (Dataplex, Unity Catalog, Collibra, ...), or scripts walking a database." OpenAPI is the most widely published API description format, so an **OpenAPI 3.x to OKF** producer is a low-friction on-ramp: any service that already publishes an OpenAPI document can expose its catalog as OKF with no hand-authoring.

I have a small, dependency-free Node producer that reads an OpenAPI 3.x document and emits a conformant OKF v0.1 bundle:

- one concept doc per operation (`type: "API Operation"`) with method, path, parameters, and relative-markdown links to the schemas it references
- one concept doc per `components.schemas` entry (`type: "Schema"`)
- frontmatter-free `index.md` / `log.md` per the spec; the bundle-root `index.md` declares `okf_version` only

It is validated against a real production API (a public event-staffing API: 7 operations, 13 schemas, producing a clean 24-file bundle).

A few questions before I open a PR, so I build it in the shape you want:

1. Would a generic OpenAPI-to-OKF producer be welcome in the repo?
2. Where would it best live, `toolbox/` (alongside `mdcode` / `enrichment`), or somewhere else? And should the example bundle go under `okf/bundles/`?
3. Do you prefer a dependency-free Node script, or TypeScript with unit tests to match the existing packages?

Happy to sign the CLA and adapt to your preferred layout and conventions.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.