# XQual API Documentation Generator — User Guide

This tool does two things :

1. Generates an OpenAPI 3.0.3 specification (`openapi.json`) from a XQual `CServer.java` source file.
2. 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.

1. Locate the XQual webapp folder on your XQual server, typically :

       /opt/tomcat/webapps/xqual/

2. 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

3. 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 :

1. `?api=<url>` query string on the doc page (e.g. `integrated-xqual-doc.html?api=https://xqual.example.com/xqual/api`)
2. `x-docgen.apiBaseUrl` field in `openapi.json`
3. 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 :

1. Re-run `run-doc-api-gen.bat` (locally or on a build agent).
2. 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

1. Generate : `run-doc-api-gen.bat` (with optional path to your Java file).
2. 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).
3. Browse : open `integrated-xqual-doc.html` in any modern browser.

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