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

[chaitanyamedidar]

Current State

• The Layer5 Cloud API Reference 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

---

Contributor Guide and Resources

• 📚 Instructions for contributing to documentation
  • Layer5 documentation site and source
• 🎨 Wireframes and designs for Layer5 site in Figma (open invite)
• 🙋🏾🙋🏼 Questions: Layer5 Discussion Forum and Layer5 Community Slack

[welcome]

Thanks for opening this issue. A contributor will be by to give feedback soon. In the meantime, please review the Layer5 Community Welcome Guide and sure to join the community Slack.

[karthik-51]

@chaitanyamedidar i want to work on this. Could you please assign it me??

[chaitanyamedidar]

Thank you for your interest!
Before we assign this issue, we'd like to understand your proposed approach a bit better, this helps us make sure the implementation aligns with what we have in mind and avoids rework later.
Please share your understanding, approach, any prior work, and any relevant PRs. Also, please let me know if you have any questions from your end.

[karthik-51]

Hi @chaitanyamedidar , Here's is my approach and we can further discuss to move forward.!!

Issue Understanding

The Layer5 Cloud REST API Reference is generated from the OpenAPI specification using custom Hugo partials. Currently, the documentation is static—it displays endpoint details, parameters, and server URLs, but doesn't allow users to execute API requests directly from the docs. As a result, developers must switch to tools like Postman or curl to test endpoints, creating unnecessary friction.

The objective of this issue is to introduce a client-side "Try it out" feature for unauthenticated GET endpoints (e.g., /api/catalog/content/{type}), enabling users to execute requests and inspect live responses directly within the documentation.

Proposed Approach

I plan to implement this with minimal changes to the existing Hugo-based architecture.

• Hugo Template Enhancement: Update viewer.html to identify eligible unauthenticated GET endpoints and expose their metadata (method, path, parameters, servers) via data-* attributes.
• Client-side Integration: Build a lightweight vanilla JavaScript module that detects these endpoints, renders a "Try it out" panel, and handles request execution.
• Request Execution: Use the browser's fetch() API to send requests to either the local development server (localhost:9876) or the production endpoint, with editable path and query parameters.
• Response Handling: Display the HTTP status, headers, and response body inline without a page refresh, while gracefully handling CORS, connection, and network errors with clear UI feedback.

Why This Approach

This solution is fully client-side, requires no backend changes or additional dependencies, and integrates cleanly with the existing Hugo documentation pipeline. Restricting the initial implementation to unauthenticated GET endpoints keeps the scope safe and manageable while providing a reusable foundation for supporting authenticated endpoints and additional HTTP methods in future iterations.

Expected Outcome

• "Try it out" is available only for approved unauthenticated GET endpoints.
• Users can execute live API requests directly from the documentation.
• Path and query parameters are editable before execution.
• Responses (status, headers, body) are rendered inline.
• CORS and connection failures are handled with user-friendly error messages.
• Existing documentation structure and rendering remain unchanged.

[vedant21-ctr]

@chaitanyamedidar i can work on this
i will share the approch for this

[vedant21-ctr]

Hi @chaitanyamedidar,

I looked through the issue and here's the approach I'd like to take:

• Instead of hardcoding supported endpoints, I'd use the OpenAPI spec as the source of truth. Only endpoints with GET + security: [] would get the Try it out widget, so any future unauthenticated GET endpoint works automatically.
• In the Hugo template, I'd expose the required endpoint metadata (path, params, servers) through data-* attributes only for eligible endpoints.
• Build one reusable JS module that reads this metadata, renders the UI, executes the request with fetch(), and displays the response (status, headers, body).
• Handle failures gracefully with a generic network/CORS message instead of trying to distinguish errors that browsers don't expose.

One question before starting: do the production/staging APIs already allow requests from the docs site via CORS? If not, only the localhost option would work initially.

If this approach looks good, I'd be happy to work on it.

[nafisa404]

Hi @chaitanyamedidar , I've been working in this repo's Hugo partials recently (#1129 — the related-reading.html migration), so I've spent time in how the custom partials and content pipeline are structured here.

A few thoughts building on what @vedant21-ctr proposed (agree that spec-driven eligibility via security: [] is the right call over hardcoding endpoints):

• Where in the OpenAPI-generation pipeline does security: [] actually get preserved through to the partial? I want to confirm the data survives from data/openapi.yml through to whatever partial renders each endpoint (looks like viewer.html per @vedant21-ctr's note) before committing to that as the eligibility check.
• For the CORS fallback: rather than a generic message, could the widget detect specifically "no CORS headers returned" vs "connection refused" by checking whether fetch() throws immediately (network/CORS) vs returns a response — that distinction is usually detectable even though the exact reason isn't, and it'd make the failure message more actionable for users debugging their own local server setup.
• Happy to scope this tightly to just /api/catalog/content/{type} for the first PR and leave the "any future unauthenticated GET" generalization as a fast-follow, if that's preferred for review size.

Would love to take this on