mirror of
https://github.com/supabase/supabase.git
synced 2026-09-06 18:11:51 +08:00
4822687a64
## I have read the CONTRIBUTING.md file.
YES
## What kind of change does this PR introduce?
Bug fix.
## What is the current behavior?
`api_v2_openapi.json` has a circular reference (`APIErrorObject.issues`
→ `APIErrorObject`), which Redocly can't flatten with `--dereferenced`
("Detected circular reference which can't be converted to JSON"). This
breaks the [weekly docs update
workflow](https://github.com/supabase/supabase/actions/runs/29709444085/job/88251269807).
## What is the new behavior?
- Drop `--dereferenced` from `dereference.api.v1` (both v1 and v2, for
consistency)
- Add a `resolveRefs` helper in `Reference.script.ts` that manually
inlines `$refs`, leaving cycles as an unresolved `$ref` instead of
expanding infinitely
- This also fix the mgmt api update workflow so manual dispatch runs
against the selected branch, by changing checkout `ref` from hardcoded
`master` to `${{ github.ref }}`.
## Additional context
Also fixes `pnpm exec redocly` → `npx --package=@redocly/cli redocly` in
the same Makefile, an unrelated pnpm 11 recursive-exec bug hit while
debugging this workflow.
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **Chores**
* Updated API specification bundling and linting commands to use the
current Redocly CLI invocation style.
* Improved documentation processing behavior for dereferenced specs,
including guidance around circular references.
* Preserved existing generated specification outputs and validation
settings.
* **Chores**
* Updated the Mgmt API docs automation workflow formatting (YAML string
quoting and schedule/input values).
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
104 lines
5.7 KiB
Makefile
104 lines
5.7 KiB
Makefile
REPO_DIR=$(shell pwd)
|
||
GENERATOR_DIR=../../../packages/generator
|
||
|
||
.PHONY: run download download.api.v1 download.storage.v1 download.tsdoc.v2 download.server.v1 transform dereference.api.v1 dereference.auth.v1 dereference.storage.v0 generate generate.sections.api.v1 format
|
||
|
||
run: download transform generate format
|
||
|
||
|
||
###############################################################################
|
||
# Download all the specs
|
||
###############################################################################
|
||
# comment out download.auth.v1 temporarily, we're manually creating the file
|
||
# download: download.api.v1 download.auth.v1 download.storage.v1 download.tsdoc.v2
|
||
download: download.api.v1 download.storage.v1 download.tsdoc.v2 download.server.v1
|
||
|
||
download.api.v1:
|
||
curl -sS https://api.supabase.com/api/v1-json > $(REPO_DIR)/api_v1_openapi.json
|
||
curl -sS https://api.supabase.com/api/v2-json > $(REPO_DIR)/api_v2_openapi.json
|
||
|
||
# This flow needs to be updated, so we'l comment out for the moment
|
||
# Manual flow for now:
|
||
# — get swagger.json (https://supabase.github.io/gotrue/swagger.json)
|
||
# — manually convert via swagger editor -> open api v3 spec
|
||
# dereference.tsdoc.v2 -> auth_v1_openapi_deparsed.json
|
||
|
||
# download.auth.v1:
|
||
# curl -sS https://supabase.github.io/gotrue/swagger.json > $(REPO_DIR)/auth_v1_openapi.json
|
||
|
||
download.storage.v1:
|
||
curl -sS https://supabase.github.io/storage/api.json > $(REPO_DIR)/storage_v0_openapi.json
|
||
|
||
# No longer updated
|
||
# download.tsdoc.v1:
|
||
# curl -sS https://supabase.github.io/supabase-js/v1/spec.json > $(REPO_DIR)/enrichments/tsdoc_v1/supabase.json
|
||
# curl -sS https://supabase.github.io/gotrue-js/v1/spec.json > $(REPO_DIR)/enrichments/tsdoc_v1/gotrue.json
|
||
# curl -sS https://supabase.github.io/postgrest-js/v1/spec.json > $(REPO_DIR)/enrichments/tsdoc_v1/postgrest.json
|
||
# curl -sS https://supabase.github.io/realtime-js/v1/spec.json > $(REPO_DIR)/enrichments/tsdoc_v1/realtime.json
|
||
# curl -sS https://supabase.github.io/storage-js/v1/spec.json > $(REPO_DIR)/enrichments/tsdoc_v1/storage.json
|
||
# curl -sS https://supabase.github.io/functions-js/v1/spec.json > $(REPO_DIR)/enrichments/tsdoc_v1/functions.json
|
||
|
||
download.tsdoc.v2:
|
||
curl -sS https://supabase.github.io/supabase-js/supabase-js/v2/spec.json > $(REPO_DIR)/reference/javascript/v2/supabase.json
|
||
curl -sS https://supabase.github.io/supabase-js/auth-js/v2/spec.json > $(REPO_DIR)/reference/javascript/v2/gotrue.json
|
||
curl -sS https://supabase.github.io/supabase-js/postgrest-js/v2/spec.json > $(REPO_DIR)/reference/javascript/v2/postgrest.json
|
||
curl -sS https://supabase.github.io/supabase-js/realtime-js/v2/spec.json > $(REPO_DIR)/reference/javascript/v2/realtime.json
|
||
curl -sS https://supabase.github.io/supabase-js/storage-js/v2/spec.json > $(REPO_DIR)/reference/javascript/v2/storage.json
|
||
curl -sS https://supabase.github.io/supabase-js/functions-js/v2/spec.json > $(REPO_DIR)/reference/javascript/v2/functions.json
|
||
|
||
download.server.v1:
|
||
curl -sSf https://supabase.github.io/server/spec.json > $(REPO_DIR)/reference/server/v1/server.json
|
||
|
||
download.analytics.v0:
|
||
curl -sS https://logflare.app/api/openapi > $(REPO_DIR)/analytics_v0_openapi.json
|
||
|
||
###############################################################################
|
||
# Transform docs into working files
|
||
###############################################################################
|
||
# `download.tsdoc.v2` now writes raw TypeDoc JSON directly under
|
||
# `reference/javascript/v2/` — the new pipeline (`scripts/build-reference-content.ts`,
|
||
# wired into `predev`/`prebuild` via `codegen:references:new`) walks those files
|
||
# at build time, so no separate `dereference` / `combine` step is needed.
|
||
transform: dereference.api.v1 dereference.auth.v1 dereference.storage.v0
|
||
|
||
# NOTE: no --dereferenced here — api_v2_openapi.json has a circular ref
|
||
# (APIErrorObject.issues -> APIErrorObject) that Redocly can't flatten to
|
||
# JSON. v1 uses the same approach for consistency.
|
||
# $refs are resolved manually in writeApiReferenceSections
|
||
dereference.api.v1:
|
||
npx --package=@redocly/cli redocly bundle -o $(REPO_DIR)/transforms/api_v1_openapi_deparsed.json $(REPO_DIR)/api_v1_openapi.json
|
||
npx --package=@redocly/cli redocly bundle -o $(REPO_DIR)/transforms/api_v2_openapi_deparsed.json $(REPO_DIR)/api_v2_openapi.json
|
||
|
||
dereference.auth.v1:
|
||
npx --package=@redocly/cli redocly bundle --dereferenced -o $(REPO_DIR)/transforms/auth_v1_openapi_deparsed.json $(REPO_DIR)/auth_v1_openapi.json
|
||
|
||
dereference.storage.v0:
|
||
npx --package=@redocly/cli redocly bundle --dereferenced -o $(REPO_DIR)/transforms/storage_v0_openapi_deparsed.json $(REPO_DIR)/storage_v0_openapi.json
|
||
|
||
dereference.analytics.v0:
|
||
npx --package=@redocly/cli redocly bundle --dereferenced -o $(REPO_DIR)/transforms/analytics_v0_openapi_deparsed.json $(REPO_DIR)/analytics_v0_openapi.json
|
||
|
||
###############################################################################
|
||
# Generate sections from OpenAPI 3.0
|
||
###############################################################################
|
||
generate: generate.sections.api.v1
|
||
|
||
generate.sections.api.v1:
|
||
npx tsx $(REPO_DIR)/sections/generateMgmtApiSections.cts \
|
||
$(REPO_DIR)/transforms/api_v1_openapi_deparsed.json \
|
||
$(REPO_DIR)/transforms/api_v2_openapi_deparsed.json \
|
||
$(REPO_DIR)/common-api-sections.json
|
||
|
||
###############################################################################
|
||
# Validate OpenAPI 3.0
|
||
###############################################################################
|
||
|
||
validate.analytics.v0:
|
||
npx --package=@redocly/cli redocly lint --extends=minimal $(REPO_DIR)/analytics_v0_openapi.json
|
||
|
||
###############################################################################
|
||
# Format everything - easier for git to track changes.
|
||
###############################################################################
|
||
format:
|
||
npx prettier --cache --write .
|