@cfxlabsinc/nx-openapi

Workspace-internal Nx plugin for CFX API projects that publish an OpenAPI spec.

Inferred targets

The plugin's createNodes watches for **/src/interface/frontMatter.ts. When it finds one in a project with a project.json, it contributes these targets, fully defined:

• gen-specs — runs tools/scripts/gen-spec.ts, writing OpenAPI 3.1 to {projectRoot}/schemas/{projectName}.json (the /v1 paths) and, when the API has /v2 routes, {projectRoot}/schemas/{projectName}.v2.json, plus {projectRoot}/schemas/{projectName}.draft-04.json: every route's request models as JSON Schema draft-04, the form API Gateway validates. The files are committed. Cached, with the committed files among its inputs, so a hand edit misses the cache.
  • gen-specs -c ci is the CI gate: gen-spec.ts --check builds the specs in memory and exits 1 when a committed file differs, is missing, or is one the generator no longer writes, naming each file and the fix (bun nx run <api>:gen-specs, then commit {projectRoot}/schemas/). It writes nothing.
• publish-specs — rdme openapi upload, dependsOn: ["gen-specs"]. The v1 spec (when the API has /v1 routes) goes to ReadMe's default version, the v2 spec to the v2.0 version (--branch=v2.0), both under the slug {projectName}.json. rdme cannot create a version, so v2.0 was made in the ReadMe dashboard; a new version needs the same.
• validate-specs — rdme openapi validate on each committed spec, dependsOn: ["gen-specs"]

Why src/interface/frontMatter.ts is the marker

gen-spec.ts imports every module in packages/<project>/src/interface/, reads FRONT_MATTER and reflects over the *Api exports. The interface folders have no barrel, so the front-matter module is the one file every spec-producing API has — the detection can't drift from what the generator actually requires.

Going by an -api name suffix or a tag would be wrong: bai2-api is an API but is written in Go, generates its spec with swag, and therefore declares its own gen-specs in project.json. It has no src/interface/frontMatter.ts, so this plugin correctly skips it.

The targetDefaults precedence rule

Nx merge order is inferred (plugin) < targetDefaults < project.json. A targetDefault overwrites every key an inferred target sets, but never a key project.json sets.

These three targets can be fully defined in the plugin only because nx.json no longer declares targetDefaults for them. Re-adding one would silently clobber the matching keys in src/plugin.ts. See @cfxlabsinc/nx-lambda for the second half of the rule (name keys shadow executor keys).

Registration

Plugin is registered in workspace nx.json under plugins:

{
  "plugin": "@cfxlabsinc/nx-openapi",
  "options": {}
}
Copy

Resolves through the workspace dependency in the root package.json:

"@cfxlabsinc/nx-openapi": "workspace:*"
Copy