[Docs] Add interactive Try it out API console to Layer5 Cloud REST API Reference
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 条评论