# Understanding the OpenAPI Documentation Endpoint in y-gui

> Discover the OpenAPI documentation endpoint in y-gui. Access machine-readable specs and an interactive Swagger UI to explore your API effectively.

- Repository: [luohy15/y-gui](https://github.com/luohy15/y-gui)
- Tags: api-reference
- Published: 2026-03-06

---

**The OpenAPI documentation endpoint in y-gui serves dual purposes: it exposes a machine-readable API specification at [`/api/docs/openapi.json`](https://github.com/luohy15/y-gui/blob/main//api/docs/openapi.json) and renders an interactive Swagger UI at `/api/docs` for human exploration.**

The y-gui backend implements a lightweight OpenAPI 3.0 specification that describes all public HTTP routes, including authentication, chat, tool, bot, and MCP-server endpoints. This self-documenting approach allows developers to discover API capabilities programmatically or through an interactive browser interface.

## Purpose of the OpenAPI Documentation Endpoint

The endpoint architecture separates concerns between machine consumption and human readability:

- **Machine-readable API definition**: A GET request to [`/api/docs/openapi.json`](https://github.com/luohy15/y-gui/blob/main//api/docs/openapi.json) returns a complete JSON document containing the OpenAPI specification. The backend constructs this dynamically by merging reusable schema definitions, security schemes, and path objects from individual modules.

- **Human-friendly exploration interface**: A GET request to `/api/docs` returns an HTML page that loads Swagger UI from a CDN and configures it to fetch the JSON specification. This allows developers to inspect endpoints, view request/response schemas, and execute test calls directly in the browser.

## Core Structure and Implementation

The OpenAPI documentation endpoint implementation resides in `backend/src/openapi/` and follows a modular architecture that separates routing, schema definitions, and UI rendering.

### Request Routing and Handler Logic

The [`backend/src/openapi/handler.ts`](https://github.com/luohy15/y-gui/blob/main/backend/src/openapi/handler.ts) file contains the main request handler that parses incoming URLs and returns the appropriate response. It inspects the request path to determine whether to serve the JSON specification, the Swagger UI HTML, or a 404 error. The handler constructs the OpenAPI document on-the-fly by assembling components from various submodules rather than serving a static file.

### Specification Assembly

The OpenAPI document construction follows a structured assembly process within the handler:

- **Info block**: Contains the API title, description, and version metadata.
- **Servers**: Defines the current server URL as `'/'`.
- **Components**: Merges `securitySchemes` and reusable `schemas` imported from [`backend/src/openapi/schemas.ts`](https://github.com/luohy15/y-gui/blob/main/backend/src/openapi/schemas.ts).
- **Paths**: Spreads path objects exported by individual route modules located in `backend/src/openapi/paths/`, including `authPaths`, `chatPaths`, `toolPaths`, `botPaths`, and MCP-server paths.

### Swagger UI Rendering

The [`backend/src/openapi/ui.ts`](https://github.com/luohy15/y-gui/blob/main/backend/src/openapi/ui.ts) file defines the HTML template returned by the `/api/docs` endpoint. This module generates a complete HTML document that loads the Swagger UI JavaScript and CSS bundles from a CDN. The configuration points the UI to fetch the OpenAPI specification from [`/api/docs/openapi.json`](https://github.com/luohy15/y-gui/blob/main//api/docs/openapi.json), enabling the interactive documentation interface without requiring any build-time bundling of the UI assets.

### Module Exports

The [`backend/src/openapi/index.ts`](https://github.com/luohy15/y-gui/blob/main/backend/src/openapi/index.ts) file serves as the public interface for the OpenAPI module. It re-exports the request handler, the Swagger UI HTML generator, and all component collections (schemas and paths) to simplify imports elsewhere in the backend codebase.

## Accessing the OpenAPI Documentation Endpoint

Developers can interact with the documentation endpoint using standard HTTP clients or browsers.

### Retrieve the Raw OpenAPI JSON

To fetch the machine-readable specification for programmatic consumption or client generation:

```bash
curl https://your-y-gui-domain.com/api/docs/openapi.json

```

The response contains the complete OpenAPI 3.0 JSON document with all paths, schemas, and security definitions.

### Open the Interactive Documentation

Navigate to the following URL in any modern web browser:

```

https://your-y-gui-domain.com/api/docs

```

The Swagger UI interface loads automatically, displaying all available endpoints, their HTTP methods, request parameters, and response schemas. You can expand any operation to see detailed documentation and execute test requests directly against the live API.

### Generate a Typed Client

Use the OpenAPI specification to generate type-safe client libraries for your preferred language. For example, generating a TypeScript Axios client:

```bash
openapi-generator-cli generate \
  -i https://your-y-gui-domain.com/api/docs/openapi.json \
  -g typescript-axios \
  -o ./generated-client

```

This command downloads the specification and generates a fully typed client that matches the y-gui API structure, complete with interfaces for request/response models and method implementations for each endpoint.

## Summary

- The **OpenAPI documentation endpoint** in y-gui provides both machine-readable JSON at [`/api/docs/openapi.json`](https://github.com/luohy15/y-gui/blob/main//api/docs/openapi.json) and an interactive Swagger UI at `/api/docs`.
- The implementation resides in `backend/src/openapi/`, with [`handler.ts`](https://github.com/luohy15/y-gui/blob/main/handler.ts) managing request routing, [`schemas.ts`](https://github.com/luohy15/y-gui/blob/main/schemas.ts) defining reusable components, and [`ui.ts`](https://github.com/luohy15/y-gui/blob/main/ui.ts) rendering the HTML interface.
- The specification is constructed dynamically by merging path definitions from modular route files in `backend/src/openapi/paths/` rather than serving static content.
- Developers can use the endpoint to generate typed clients, validate API implementations, or explore capabilities through the browser-based UI.

## Frequently Asked Questions

### What is the exact URL path for the OpenAPI JSON specification in y-gui?

The machine-readable OpenAPI 3.0 specification is available at **[`/api/docs/openapi.json`](https://github.com/luohy15/y-gui/blob/main//api/docs/openapi.json)**. This endpoint returns a complete JSON document containing all API paths, request/response schemas, and security definitions. The backend constructs this response dynamically in [`backend/src/openapi/handler.ts`](https://github.com/luohy15/y-gui/blob/main/backend/src/openapi/handler.ts) by assembling components from various path modules and schema definitions.

### How does y-gui serve the Swagger UI interface?

The Swagger UI is served from **`/api/docs`** via the handler defined in [`backend/src/openapi/handler.ts`](https://github.com/luohy15/y-gui/blob/main/backend/src/openapi/handler.ts). When this endpoint receives a GET request, it returns HTML content generated by [`backend/src/openapi/ui.ts`](https://github.com/luohy15/y-gui/blob/main/backend/src/openapi/ui.ts). This HTML loads the Swagger UI JavaScript and CSS from a CDN and configures it to fetch the OpenAPI specification from [`/api/docs/openapi.json`](https://github.com/luohy15/y-gui/blob/main//api/docs/openapi.json), creating an interactive documentation interface without requiring any build-time asset bundling.

### Can I use the OpenAPI specification to generate client code for y-gui?

Yes, the [`/api/docs/openapi.json`](https://github.com/luohy15/y-gui/blob/main//api/docs/openapi.json) endpoint provides a standard OpenAPI 3.0 specification that is compatible with code generation tools such as OpenAPI Generator or Swagger Codegen. You can point these tools at the live JSON endpoint to generate type-safe clients in languages like TypeScript, Python, or Java. For example, using the OpenAPI Generator CLI with the `-i` flag set to your y-gui domain followed by [`/api/docs/openapi.json`](https://github.com/luohy15/y-gui/blob/main//api/docs/openapi.json) will produce a fully typed client library complete with request/response interfaces.

### Where are the API path definitions stored in the y-gui source code?

Individual API route definitions are modularized and stored in the `backend/src/openapi/paths/` directory. This directory contains separate files for each functional area, such as authentication, chat, tools, bots, and MCP-server routes. The main handler in [`backend/src/openapi/handler.ts`](https://github.com/luohy15/y-gui/blob/main/backend/src/openapi/handler.ts) imports these path objects and merges them into the final OpenAPI specification by spreading them into the `paths` property of the document object.