ITADN

[Docs] Add interactive Try it out API console to Layer5 Cloud REST API Reference

#1134Openchaitanyamedidar 创建于 2026-07-01
help wantedkind/enhancementlanguage/javascriptlanguage/csslanguage/htmlframework/hugo
### Current State - The [Layer5 Cloud API Reference](https://docs.layer5.io/cloud/reference/api-reference/rest/) is auto-generated from OpenAPI schemas using custom Hugo partials. - Each endpoint entry displays the resolvable server URL (e.g., Layer5 Cloud local server URL: `http://localhost:9876/api/...`), but this is entirely static. - There is no way to actually send a request from the docs page and see what comes back. A user has to manually copy the URL/parameters into `curl` or Postman. ### Desired State On each endpoint's docs page, add an interactive "Try it out" widget. **For V1, this feature is strictly scoped to unauthenticated `GET` endpoints, specifically:** - `/api/catalog/content/{type}` - *(Any other unauthenticated catalog retrieval endpoints)* The interactive widget should: 1. Render as a client-side component embedded in the existing Hugo partials. 2. Allow the user to target their local dev server (`localhost:9876`) or the public production endpoint (`https://meshery.layer5.io`). 3. Render editable input fields for path and query parameters. 4. Execute the actual HTTP request client-side (via browser `fetch()` from the user's machine to the Cloud instance). 5. Display the real status code, headers, and response body dynamically without refreshing the page. 6. Fall back gracefully (displaying a clear error message in the UI) when the target server isn't reachable due to CORS failures or connection refused errors. ### Why - Directly enables users testing Layer5 Cloud to understand "what does this endpoint actually return" without leaving the docs. - Scoping to unauthenticated `GET` endpoints for V1 avoids the complexity of injecting authentication tokens and eliminates the risk of accidental data mutation in the database, allowing us to establish the baseline UI safely. ### Implementation Plan 1. **Architecture:** Because the REST API Reference is built using custom Hugo partials, this will require injecting a custom vanilla JavaScript bundle or HTML snippet that attaches to the generated endpoint sections. 2. **Component Logic:** The JavaScript should read the parameters from the DOM, construct the `fetch()` call to the selected URL, and render the raw response back into the DOM. 3. **CORS:** Ensure the UI clearly instructs users that this only works against instances configured to allow cross-origin requests from the docs site (or against the public catalog endpoints). 4. **Scoping:** Enforce that the "Try it out" button **only** renders for approved HTTP `GET` catalog operations. Do not include token inputs or `POST/PUT` body editors in this initial PR. ### Acceptance Criteria - [ ] A "Try it out" control is visible exclusively on unauthenticated `GET` endpoint pages (e.g. `/api/catalog/content/{type}`) in the Layer5 Cloud REST API Reference. - [ ] A user can execute a real request against a running server and see the actual response rendered inside the docs page. - [ ] Path and query parameters are editable inputs feeding the executed request. - [ ] The target server defaults to the local dev server URL. - [ ] Failure states (unreachable server, CORS error) are shown as a readable message in the panel, not a silent failure. - [ ] No regression to the existing static documentation formatting. ### Mockups <!-- [Optional] Any visual diagrams of the desired user interface. --> --- #### Contributor Guide and Resources - 📚 [Instructions for contributing to documentation](https://github.com/layer5io/docs/blob/master/CONTRIBUTING.md) - Layer5 documentation [site](https://docs.layer5.io) and [source](https://github.com/layer5io/docs/) - 🎨 Wireframes and [designs for Layer5 site](https://www.figma.com/file/5ZwEkSJwUPitURD59YHMEN/Layer5-Designs) in Figma [(open invite)](https://www.figma.com/team_invite/redeem/GvB8SudhEOoq3JOvoLaoMs) - 🙋🏾🙋🏼 Questions: [Layer5 Discussion Forum](https://discuss.layer5.io) and [Layer5 Community Slack](http://slack.layer5.io)
1 条评论