Understanding the OpenAPI Documentation Endpoint in y-gui

The OpenAPI documentation endpoint in y-gui serves dual purposes: it exposes a machine-readable API specification at /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 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 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.
• 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 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, enabling the interactive documentation interface without requiring any build-time bundling of the UI assets.

Module Exports

The 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:

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:

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 and an interactive Swagger UI at /api/docs.
• The implementation resides in backend/src/openapi/, with handler.ts managing request routing, schemas.ts defining reusable components, and 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. 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 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. When this endpoint receives a GET request, it returns HTML content generated by 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, 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 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 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 imports these path objects and merges them into the final OpenAPI specification by spreading them into the paths property of the document object.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}