XQual API Documentation Generator — User Guide

This tool does two things :

Generates an OpenAPI 3.0.3 specification (openapi.json) from a XQual CServer.java source file.
Provides a ready-to-host HTML viewer (integrated-xqual-doc.html) that renders the spec and lets you fire real GET/POST requests against your XQual test server.

You host the two files on your own web server (typically the same Tomcat that serves XQual). There is no server bundled in this package.

Package layout

README.html                        ← this guide
run-doc-api-gen.bat                ← double-click to (re)generate the JSON
bin/
  api-doc-generator-win.exe        ← the generator CLI
samples/
  CServer.java                     ← sample Java source (used by default)
output/
  integrated-xqual-doc.html        ← static, pre-built viewer (host as-is)
  openapi.json                     ← produced by the .bat (host alongside the HTML)
  xqual-api-doc-deploy.zip         ← produced by the .bat: HTML + JSON ready to upload

Step 1 — Generate the OpenAPI spec

Default (use the bundled sample):

Double-click run-doc-api-gen.bat. It writes output/openapi.json.

With your own Java source:

Open a terminal in the package folder and run :

run-doc-api-gen.bat C:\path\to\your\CServer.java

or call the generator directly :

bin\api-doc-generator-win.exe -i C:\path\to\CServer.java -o output\openapi.json

Optional Java annotations (recommended)

Annotate each endpoint block in CServer.java to enrich the documentation :

if (command.equalsIgnoreCase("getUsersTree")) {
    // @section: Users
    // @version: 11+
    // @description: Returns the user tree
    String cache = request.getParameter("cache");
    output = CApiXStudioWeb_User.getUsersTree(session, cache);
}

@section: → category in the doc. If missing, inferred from the CApiXStudioWeb_* class name (e.g. CApiXStudioWeb_User → "Users").
@version: → minimum supported version. Defaults to 8+.
@description: → short prose summary (basic mode only).

Step 2 — Host the doc on your server

The .bat produces output/xqual-api-doc-deploy.zip containing the two files you need to ship :

integrated-xqual-doc.html
openapi.json

Upload the zip, unzip it inside a folder served by your web server, and keep both files in the same folder — the HTML loads the JSON via a relative fetch("openapi.json").

Recommended : host inside the XQual Tomcat (same origin)

This is the simplest setup — no CORS configuration is needed and the "Try It" calls reuse the user's existing XQual session cookie.

Locate the XQual webapp folder on your XQual server, typically :
```
/opt/tomcat/webapps/xqual/
```

Create a sub-folder for the doc and drop both files in it :

sudo mkdir -p /opt/tomcat/webapps/xqual/api-doc
sudo cp integrated-xqual-doc.html openapi.json /opt/tomcat/webapps/xqual/api-doc/
sudo chown -R tomcat:tomcat /opt/tomcat/webapps/xqual/api-doc

Access the doc :
```
https://<your-xqual-host>/xqual/api-doc/integrated-xqual-doc.html
```
The user must be logged into XQual in the same browser tab so the JSESSIONID cookie is sent with Try-It requests.

Alternative : host on a different domain (CORS required)

If you host the doc on a different host than XQual, the browser will block Try-It calls unless Tomcat returns CORS headers. Edit $CATALINA_HOME/conf/web.xml (global) or WEB-INF/web.xml of the XQual webapp and add :

<filter>
  <filter-name>CorsFilter</filter-name>
  <filter-class>org.apache.catalina.filters.CorsFilter</filter-class>
  <init-param>
    <param-name>cors.allowed.origins</param-name>
    <param-value>https://your-doc-host.example.com</param-value>
  </init-param>
  <init-param>
    <param-name>cors.allowed.methods</param-name>
    <param-value>GET,POST,OPTIONS</param-value>
  </init-param>
  <init-param>
    <param-name>cors.allowed.headers</param-name>
    <param-value>Content-Type,Authorization,X-Requested-With</param-value>
  </init-param>
  <init-param>
    <param-name>cors.support.credentials</param-name>
    <param-value>true</param-value>
  </init-param>
</filter>
<filter-mapping>
  <filter-name>CorsFilter</filter-name>
  <url-pattern>/api/*</url-pattern>
</filter-mapping>

Restart Tomcat. The browser must also allow third-party cookies (or you must pass credentials another way) for the session cookie to travel with Try-It calls.

Alternative : nginx (static + reverse-proxy to avoid CORS)

If your doc is served by nginx and XQual lives elsewhere, the cleanest way is to reverse-proxy /api/ from nginx to Tomcat. The browser only sees one origin → no CORS at all.

server {
    listen 80;
    server_name doc.example.com;

    # 1) Static viewer + openapi.json
    root /var/www/xqual-api-doc;
    index integrated-xqual-doc.html;

    location / {
        try_files $uri $uri/ =404;
    }

    # 2) Reverse-proxy XQual API under the SAME origin
    location /api/ {
        proxy_pass         http://xqual-host:8080/xqual/api/;
        proxy_set_header   Host              $host;
        proxy_set_header   X-Real-IP         $remote_addr;
        proxy_set_header   X-Forwarded-For   $proxy_add_x_forwarded_for;
        proxy_set_header   X-Forwarded-Proto $scheme;
        proxy_cookie_path  /xqual/ /;
        proxy_pass_request_headers on;
    }
}

Drop integrated-xqual-doc.html and openapi.json into /var/www/xqual-api-doc/, nginx -t && systemctl reload nginx, done.

If you prefer pure static (no proxy), see the CORS section above — you'll need to configure Tomcat's CorsFilter on the XQual side.

Alternative : Apache httpd (mod_proxy)

Same idea with Apache :

<VirtualHost *:80>
    ServerName  doc.example.com
    DocumentRoot /var/www/xqual-api-doc
    DirectoryIndex integrated-xqual-doc.html

    <Directory /var/www/xqual-api-doc>
        Require all granted
    </Directory>

    # Reverse-proxy XQual API under the same origin
    ProxyPreserveHost On
    ProxyPass         /api/  http://xqual-host:8080/xqual/api/
    ProxyPassReverse  /api/  http://xqual-host:8080/xqual/api/
    ProxyPassReverseCookiePath /xqual/ /
</VirtualHost>

Required modules : proxy, proxy_http. Enable with a2enmod proxy proxy_http && systemctl reload apache2.

Alternative : any static host (S3, GitHub Pages, Netlify…)

The viewer is pure HTML/JS — any static host works. Same caveat for CORS if it's a different origin than the XQual API : either configure Tomcat's CorsFilter (see above) or front the API with a reverse-proxy on the doc's origin.

Pointing "Try It" at your XQual server

The "Try It" button issues a real HTTP call. The viewer needs to know where to send it. Resolution order :

?api=<url> query string on the doc page (e.g. integrated-xqual-doc.html?api=https://xqual.example.com/xqual/api)
x-docgen.apiBaseUrl field in openapi.json
Default : api (relative — works when the doc is hosted inside the XQual webapp or behind a reverse-proxy mapping /api/ to XQual)

The call is sent with credentials: 'include' so the browser's JSESSIONID cookie travels with the request — the user must be logged into XQual in another tab of the same browser.

If the API origin differs from the doc origin you must either configure CORS on Tomcat (cors.support.credentials=true + explicit cors.allowed.origins) or front XQual with the nginx / Apache reverse-proxy shown above.

Updating the doc

When the Java source changes :

Re-run run-doc-api-gen.bat (locally or on a build agent).
Replace only openapi.json on the server — the HTML never changes.

Troubleshooting

Symptom	Likely cause	Fix
Empty viewer / spinner forever	`openapi.json` not found next to the HTML	Make sure both files are in the same folder, accessible via the same URL prefix.
Try-It returns CORS error	Doc hosted on a different origin than XQual	Configure Tomcat `CorsFilter` (see above), or host the doc inside the XQual webapp.
Try-It returns `401 Unauthorized`	No active XQual session in the browser	Log into XQual in another tab of the same browser first.
Generation crashes on a huge Java file	File too large or unusual structure	Try splitting the source, or run with `--verbose` from a terminal to get the stack trace.

Summary

Generate : run-doc-api-gen.bat (with optional path to your Java file).
Upload : copy output/xqual-api-doc-deploy.zip to your web server and unzip it (ideally inside the XQual Tomcat webapp, or behind an nginx / Apache reverse-proxy to avoid CORS entirely).
Browse : open integrated-xqual-doc.html in any modern browser.

That's it — your XQual REST API is documented and explorable.