Use Semi-Automatic OpenAPI Specs of the Backend API#3300
Merged
Conversation
Contributor
|
Important Review skippedAuto reviews are disabled on this repository. To trigger a review, include You can disable this status message by setting the Use the checkbox below for a quick retry:
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 2
🧹 Nitpick comments (2)
types/api/configs.ts (1)
1-4: Preferreadonlyfields for API config payloads.These values are response metadata and should not be mutable in consumer code.
As per coding guidelines: "Use `readonly` properties for object types by default to prevent accidental mutation; omit `readonly` only when the property is genuinely mutable."♻️ Suggested refactor
export interface BackendConfig { - chain_type: string; - openapi_spec_folder_name: string; + readonly chain_type: string; + readonly openapi_spec_folder_name: string; }🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@types/api/configs.ts` around lines 1 - 4, Update the BackendConfig interface so its response metadata fields are immutable: change the properties on BackendConfig (chain_type and openapi_spec_folder_name) to readonly fields; locate the BackendConfig declaration in types/api/configs.ts and convert each property to readonly to prevent accidental mutation by consumers.ui/apiDocs/RestApi.tsx (1)
19-26: Scope these queries toconfig.apis.generaltoo.This avoids unnecessary
config_backend*requests when the general API section is unavailable.♻️ Suggested refactor
refetchOnMount: false, - enabled: config.features.apiDocs.isEnabled, + enabled: config.features.apiDocs.isEnabled && Boolean(config.apis.general), @@ refetchOnMount: false, - enabled: config.features.apiDocs.isEnabled, + enabled: config.features.apiDocs.isEnabled && Boolean(config.apis.general),🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@ui/apiDocs/RestApi.tsx` around lines 19 - 26, The queries created with useApiQuery (e.g., the configVersionQuery) are only gated by config.features.apiDocs.isEnabled and should also check that the general API section is available; update the queryOptions.enabled for the relevant useApiQuery calls to require both config.features.apiDocs.isEnabled && config.apis.general (or the equivalent truthy check on config.apis.general) so the requests are skipped when the general API is not present.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@ui/apiDocs/RestApi.tsx`:
- Around line 58-60: The code currently returns the hardcoded REST_API_SECTIONS
when coreApiSwaggerUrl is falsy, which reintroduces the static core spec URL;
update the logic in RestApi.tsx (the block referencing coreApiSwaggerUrl and
REST_API_SECTIONS) to avoid falling back to REST_API_SECTIONS — instead return
an empty array or a filtered list that excludes the core/static section so the
UI only uses resolved config URLs (or handle the missing URL upstream), ensuring
the component does not reintroduce the hardcoded core spec.
In `@ui/apiDocs/utils.ts`:
- Around line 41-43: The current substring replace of DEFAULT_SERVER_NEW can
leave stray ports; instead parse req.url into a URL object, set url.protocol =
config.apis.general.protocol, url.hostname = config.apis.general.host and then
if config.apis.general.port set url.port = config.apis.general.port else set
url.port = '' to remove any original port, and return that URL; apply the same
change to the similar block referenced at lines 49-53 so both places use URL
parsing and explicit protocol/hostname/port assignment rather than string
replacement.
---
Nitpick comments:
In `@types/api/configs.ts`:
- Around line 1-4: Update the BackendConfig interface so its response metadata
fields are immutable: change the properties on BackendConfig (chain_type and
openapi_spec_folder_name) to readonly fields; locate the BackendConfig
declaration in types/api/configs.ts and convert each property to readonly to
prevent accidental mutation by consumers.
In `@ui/apiDocs/RestApi.tsx`:
- Around line 19-26: The queries created with useApiQuery (e.g., the
configVersionQuery) are only gated by config.features.apiDocs.isEnabled and
should also check that the general API section is available; update the
queryOptions.enabled for the relevant useApiQuery calls to require both
config.features.apiDocs.isEnabled && config.apis.general (or the equivalent
truthy check on config.apis.general) so the requests are skipped when the
general API is not present.
ℹ️ Review info
Configuration used: Repository UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (45)
configs/app/features/apiDocs.tsconfigs/envs/.env.arbitrumconfigs/envs/.env.arbitrum_novaconfigs/envs/.env.arbitrum_sepoliaconfigs/envs/.env.baseconfigs/envs/.env.blackfort_testnetconfigs/envs/.env.celoconfigs/envs/.env.celo_sepoliaconfigs/envs/.env.ethconfigs/envs/.env.eth_sepoliaconfigs/envs/.env.filecoinconfigs/envs/.env.garnetconfigs/envs/.env.gnosisconfigs/envs/.env.immutableconfigs/envs/.env.mainconfigs/envs/.env.mega_ethconfigs/envs/.env.mekongconfigs/envs/.env.neon_devnetconfigs/envs/.env.numineconfigs/envs/.env.optimismconfigs/envs/.env.optimism_sepoliaconfigs/envs/.env.polygonconfigs/envs/.env.rari_testnetconfigs/envs/.env.rootstock_testnetconfigs/envs/.env.scroll_sepoliaconfigs/envs/.env.shibariumconfigs/envs/.env.stability_testnetconfigs/envs/.env.tacconfigs/envs/.env.tac_spbconfigs/envs/.env.zetachainconfigs/envs/.env.zetachain_testnetconfigs/envs/.env.zilliqaconfigs/envs/.env.zkevmconfigs/envs/.env.zksyncconfigs/envs/.env.zoradeploy/tools/envs-validator/schemas/features/apiDocs.tsdeploy/tools/envs-validator/test/.env.basedocs/DEPRECATED_ENVS.mddocs/ENVS.mdlib/api/services/general/misc.tstools/preset-sync/index.tstypes/api/configs.tsui/apiDocs/RestApi.tsxui/apiDocs/utils.tsui/snippets/footer/Footer.tsx
💤 Files with no reviewable changes (38)
- configs/envs/.env.optimism
- configs/envs/.env.eth_sepolia
- configs/envs/.env.zilliqa
- configs/envs/.env.eth
- configs/envs/.env.arbitrum_nova
- configs/envs/.env.zora
- configs/envs/.env.gnosis
- configs/envs/.env.rootstock_testnet
- configs/envs/.env.zksync
- configs/envs/.env.zetachain_testnet
- configs/envs/.env.celo
- configs/envs/.env.base
- configs/envs/.env.neon_devnet
- configs/app/features/apiDocs.ts
- deploy/tools/envs-validator/test/.env.base
- configs/envs/.env.scroll_sepolia
- deploy/tools/envs-validator/schemas/features/apiDocs.ts
- configs/envs/.env.optimism_sepolia
- configs/envs/.env.arbitrum_sepolia
- configs/envs/.env.zetachain
- configs/envs/.env.garnet
- configs/envs/.env.main
- configs/envs/.env.tac
- configs/envs/.env.shibarium
- configs/envs/.env.polygon
- configs/envs/.env.blackfort_testnet
- configs/envs/.env.zkevm
- configs/envs/.env.immutable
- configs/envs/.env.celo_sepolia
- configs/envs/.env.rari_testnet
- configs/envs/.env.numine
- docs/ENVS.md
- configs/envs/.env.mega_eth
- configs/envs/.env.mekong
- configs/envs/.env.arbitrum
- configs/envs/.env.stability_testnet
- configs/envs/.env.filecoin
- configs/envs/.env.tac_spb
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description and Related Issue(s)
Resolves #3204
Starting with backend v9, semi-automatic OpenAPI specs are generated per release and chain type and stored in the blockscout/swaggers repo. This PR updates the frontend to use those specs instead of a single static Swagger URL.
The REST API docs page now derives the core API spec URL from the backend: it fetches
api/v2/config/backend-version(for the release number) andapi/v2/config/backend(foropenapi_spec_folder_name), then builds the URL ashttps://raw.githubusercontent.com/blockscout/swaggers/master/blockscout/{release}/{folder}/swagger.yaml. This ensures the displayed spec matches the running backend, including non-release builds (e.g.v9.3.2+commit.a7ab3460).Proposed Changes
RestApifetches backend config and backend version, shows a loader while loading, then builds the core API Swagger URL from the response (release number +openapi_spec_folder_name). Other API sections (stats, bens, etc.) are unchanged.config_backend_versionand use existingconfig_backend; extended types withBackendVersionConfigandBackendConfig(includingopenapi_spec_folder_name).NEXT_PUBLIC_API_SPEC_URLfrom app config and from the envs validator schema; added it to preset-sync ignore list and toDEPRECATED_ENVS.md. Removed the variable from all env presets and fromdocs/ENVS.md.Environment variable changes
NEXT_PUBLIC_API_SPEC_URL— The REST API spec URL is now built automatically from the backend version andopenapi_spec_folder_namereturned byapi/v2/config/backend-versionandapi/v2/config/backend, so this variable is no longer used. It is documented indocs/DEPRECATED_ENVS.md(deprecated in an upcoming release).Breaking or Incompatible Changes
NEXT_PUBLIC_API_SPEC_URL. Deployments that set a custom spec URL will now always see the spec that matches their backend version from the swaggers repo. If the backend does not expose the new config endpoints or the expected fields, the core API section may not load (fallback to a hardcoded URL was removed).Additional Information
https://raw.githubusercontent.com/blockscout/swaggers/master/blockscout/{release_number}/{chain_type}/swagger.yaml(e.g.9.3.2,ethereum).backend_version(e.g.v9.3.2orv9.3.2+commit.a7ab3460).Checklist for PR author
Made with Cursor