You are viewing a plain text version of this content. The canonical link for it is here.
Posted to java-commits@axis.apache.org by ro...@apache.org on 2026/05/12 02:16:35 UTC
(axis-axis2-java-core) branch master updated (b06ad9ecaa -> 78234f36a8)
This is an automated email from the ASF dual-hosted git repository.
robertlazarski pushed a change to branch master
in repository https://gitbox.apache.org/repos/asf/axis-axis2-java-core.git
from b06ad9ecaa docs: Mention Gson alongside Moshi in OpenAPI REST userguide
new 45b1465dbd docs: Remove openapi-rest-advanced-http2-userguide.xml (redundant)
new 78234f36a8 docs: Add JPA schema generation and pagination guides
The 2 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails. The revisions
listed as "add" were already present in the repository and have only
been added to this reference.
Summary of changes:
src/site/xdoc/docs/json-pagination.xml | 172 +++++++++
src/site/xdoc/docs/json-rpc-mcp-guide.xml | 10 +-
.../docs/json-springboot-tomcat11-userguide.xml | 4 +-
src/site/xdoc/docs/json-springboot-userguide.xml | 4 +-
src/site/xdoc/docs/openapi-jpa-schema.xml | 211 +++++++++++
.../docs/openapi-rest-advanced-http2-userguide.xml | 413 ---------------------
src/site/xdoc/docs/toc.xml | 14 +-
7 files changed, 396 insertions(+), 432 deletions(-)
create mode 100644 src/site/xdoc/docs/json-pagination.xml
create mode 100644 src/site/xdoc/docs/openapi-jpa-schema.xml
delete mode 100644 src/site/xdoc/docs/openapi-rest-advanced-http2-userguide.xml
(axis-axis2-java-core) 01/02: docs: Remove openapi-rest-advanced-http2-userguide.xml (redundant)
Posted by ro...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
robertlazarski pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/axis-axis2-java-core.git
commit 45b1465dbd324dba64bcfdbc8012c1e94dc885fc
Author: Robert Lazarski <ro...@gmail.com>
AuthorDate: Mon May 11 10:22:27 2026 -1000
docs: Remove openapi-rest-advanced-http2-userguide.xml (redundant)
This file was 95% duplicated content from:
- openapi-rest-userguide.xml (OpenAPI guidance)
- http2-integration-guide.xml (HTTP/2 architecture)
- http2-transport-additions.xml (transport details)
- tomcat-http2-integration-guide.xml (Tomcat config)
The remaining 5% was hallucinated: openapi.properties flags
(prettyPrint, deepLinking, filter) that don't exist in the
codebase, and @OpenApiOperation(protocols={"HTTP/2.0"}) which
is not a real annotation.
Removing eliminates a maintenance burden (6 files to sync
instead of 4) and a source of conflicting/fake configuration
examples.
Co-Authored-By: Claude Opus 4.6 (1M context) <no...@anthropic.com>
---
.../docs/json-springboot-tomcat11-userguide.xml | 4 +-
src/site/xdoc/docs/json-springboot-userguide.xml | 4 +-
.../docs/openapi-rest-advanced-http2-userguide.xml | 413 ---------------------
src/site/xdoc/docs/toc.xml | 4 +-
4 files changed, 3 insertions(+), 422 deletions(-)
diff --git a/src/site/xdoc/docs/json-springboot-tomcat11-userguide.xml b/src/site/xdoc/docs/json-springboot-tomcat11-userguide.xml
index 94bff890a8..15f7315a60 100644
--- a/src/site/xdoc/docs/json-springboot-tomcat11-userguide.xml
+++ b/src/site/xdoc/docs/json-springboot-tomcat11-userguide.xml
@@ -140,9 +140,7 @@ For comprehensive HTTP/2 configuration details and advanced features, see the
<a href="http2-transport-additions.html">HTTP/2 Transport documentation</a>.</p>
<p><strong>OpenAPI Integration:</strong> For REST API documentation and enterprise features,
-see the <a href="openapi-rest-advanced-http2-userguide.html">OpenAPI + HTTP/2 Performance Integration Guide</a>,
-which demonstrates Axis2's unique competitive advantage for modern, high-performance REST API deployments with automatic
-OpenAPI 3.0.1 specification generation and interactive Swagger UI over HTTP/2 transport.</p>
+see the <a href="openapi-rest-userguide.html">OpenAPI REST User Guide</a>.</p>
<h3>Key HTTP/2 Benefits</h3>
diff --git a/src/site/xdoc/docs/json-springboot-userguide.xml b/src/site/xdoc/docs/json-springboot-userguide.xml
index cf65ffefef..e7ed156876 100644
--- a/src/site/xdoc/docs/json-springboot-userguide.xml
+++ b/src/site/xdoc/docs/json-springboot-userguide.xml
@@ -78,9 +78,7 @@ For comprehensive HTTP/2 configuration details and advanced features, see the
<a href="http2-transport-additions.html">HTTP/2 Transport documentation</a>.</p>
<p><strong>OpenAPI Integration:</strong> For REST API documentation and enterprise features,
-see the <a href="openapi-rest-advanced-http2-userguide.html">OpenAPI + HTTP/2 Performance Integration Guide</a>,
-which demonstrates Axis2's unique competitive advantage for modern, high-performance REST API deployments with automatic
-OpenAPI 3.0.1 specification generation and interactive Swagger UI over HTTP/2 transport.</p>
+see the <a href="openapi-rest-userguide.html">OpenAPI REST User Guide</a>.</p>
<h3>Key HTTP/2 Benefits</h3>
diff --git a/src/site/xdoc/docs/openapi-rest-advanced-http2-userguide.xml b/src/site/xdoc/docs/openapi-rest-advanced-http2-userguide.xml
deleted file mode 100644
index 8303d0d5cf..0000000000
--- a/src/site/xdoc/docs/openapi-rest-advanced-http2-userguide.xml
+++ /dev/null
@@ -1,413 +0,0 @@
-<!--
- ~ Licensed to the Apache Software Foundation (ASF) under one
- ~ or more contributor license agreements. See the NOTICE file
- ~ distributed with this work for additional information
- ~ regarding copyright ownership. The ASF licenses this file
- ~ to you under the Apache License, Version 2.0 (the
- ~ "License"); you may not use this file except in compliance
- ~ with the License. You may obtain a copy of the License at
- ~
- ~ http://www.apache.org/licenses/LICENSE-2.0
- ~
- ~ Unless required by applicable law or agreed to in writing,
- ~ software distributed under the License is distributed on an
- ~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
- ~ KIND, either express or implied. See the License for the
- ~ specific language governing permissions and limitations
- ~ under the License.
- -->
-
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
- "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
-<html xmlns="http://www.w3.org/1999/xhtml">
-<head>
- <meta http-equiv="content-type" content=""/>
- <title>Apache Axis2 OpenAPI + HTTP/2 Performance Integration Guide</title>
-</head>
-
-<body lang="en">
-
-<h1>Apache Axis2 OpenAPI + HTTP/2 Performance Integration Guide</h1>
-
-<div style="background-color: #e8f5e8; border: 1px solid #4CAF50; padding: 15px; margin: 15px 0;">
-<strong>🚀 HTTP/2 + OpenAPI Integration:</strong> Apache Axis2 provides comprehensive HTTP/2 optimization
-specifically designed for OpenAPI services, delivering performance improvements for modern
-REST API deployments through native transport integration.
-</div>
-
-<h2>Overview</h2>
-
-<p>This guide demonstrates how Apache Axis2's native HTTP/2 transport delivers significant performance
-improvements for OpenAPI-enabled REST services. By combining Axis2's enterprise-grade OpenAPI implementation
-with its production-ready HTTP/2 transport, you can achieve meaningful performance improvements while maintaining
-full compatibility with existing applications. Actual gains depend on payload size, network conditions,
-and server configuration.</p>
-
-<p><strong>Key Benefits:</strong></p>
-<ul>
- <li><strong>30% faster Swagger UI loading</strong> through HTTP/2 connection multiplexing</li>
- <li><strong>40% improvement in large JSON response processing</strong> (10MB+ API responses)</li>
- <li><strong>20% reduction in memory usage</strong> through optimized connection pooling</li>
- <li><strong>80% fewer connections</strong> via HTTP/2 multiplexing (50 connections → 10 multiplexed)</li>
- <li><strong>Enterprise-ready deployment</strong> with WildFly HTTP/2 integration</li>
-</ul>
-
-<h2>HTTP/2 Benefits for OpenAPI Services</h2>
-
-<h3>Large OpenAPI Specification Delivery</h3>
-
-<p>Modern enterprise APIs often generate large OpenAPI specifications (1-10MB) due to comprehensive schemas,
-extensive security definitions, and numerous endpoints. HTTP/2 connection multiplexing dramatically improves
-the delivery of these large specifications:</p>
-
-<p><em>(Illustrative estimates — actual results depend on payload, network, and JVM configuration.)</em></p>
-<table border="1">
-<tr><th>Specification Size</th><th>HTTP/1.1 (baseline)</th><th>HTTP/2 Performance</th><th>Improvement</th></tr>
-<tr><td>1-3MB (typical enterprise)</td><td>2.5s</td><td>1.8s</td><td>28% faster</td></tr>
-<tr><td>3-7MB (complex APIs)</td><td>5.2s</td><td>3.1s</td><td>40% faster</td></tr>
-<tr><td>7-10MB+ (microservices)</td><td>8.7s</td><td>5.2s</td><td>40% faster</td></tr>
-</table>
-
-<h3>Swagger UI Asset Multiplexing</h3>
-
-<p>Swagger UI requires loading multiple assets (CSS, JavaScript, fonts, icons). HTTP/2 multiplexing
-delivers all assets over a single connection, eliminating connection setup overhead:</p>
-
-<ul>
- <li><strong>HTTP/1.1</strong>: 6-8 separate connections for UI assets (connection overhead: ~800ms)</li>
- <li><strong>HTTP/2</strong>: Single multiplexed connection for all assets (overhead: ~150ms)</li>
- <li><strong>Result</strong>: Significantly faster UI initialization (illustrative estimate; actual improvement depends on asset count and network latency)</li>
-</ul>
-
-<h3>Large API Response Optimization</h3>
-
-<p>Enterprise APIs frequently return large JSON responses (analytics data, bulk exports, reporting).
-HTTP/2 streaming and flow control provide significant benefits:</p>
-
-<pre>
-// Example: Financial analytics API returning 50MB JSON dataset
-HTTP/1.1: 12.3s total processing time
-HTTP/2: 7.4s total processing time
-Improvement: 40% faster processing with 20% less memory usage
-</pre>
-
-<h2>Quick Start Configuration</h2>
-
-<h3>1. Enable HTTP/2 Transport</h3>
-
-<p>Configure Axis2 to use HTTP/2 transport with intelligent defaults:</p>
-
-<pre>
-<!-- axis2.xml - HTTP/2 Transport Configuration -->
-<transportSender name="h2" class="org.apache.axis2.transport.h2.impl.httpclient5.H2TransportSender">
- <parameter name="PROTOCOL">HTTP/2.0</parameter>
- <!-- Intelligent defaults optimize for OpenAPI workloads -->
-</transportSender>
-</pre>
-
-<h3>2. Configure OpenAPI for HTTP/2</h3>
-
-<p>Enable OpenAPI with HTTP/2 optimizations:</p>
-
-<pre>
-# openapi.properties - HTTP/2 Optimized Configuration
-openapi.title=High-Performance Trading API
-openapi.description=HTTP/2 optimized enterprise trading platform with sub-second response times
-openapi.version=2.0.0-h2
-
-# OpenAPI UI settings (standard Swagger UI properties)
-openapi.prettyPrint=false # Reduce JSON size
-openapi.swaggerUi.deepLinking=true # Enable efficient navigation
-openapi.swaggerUi.filter=true # Optimize large API browsing
-
-# Note: HTTP/2 transport and streaming are configured in axis2.xml
-# by selecting the appropriate transport sender and message formatter.
-# No openapi.properties flags are needed for HTTP/2.
-</pre>
-
-<h3>3. Service Configuration</h3>
-
-<p>Configure services to use HTTP/2 transport:</p>
-
-<pre>
-// Java Service Configuration
-@WebService
-@OpenApiOperation(
- value = "Get large dataset",
- notes = "HTTP/2 optimized for 50MB+ JSON responses",
- protocols = {"HTTP/2.0"}
-)
-public class AnalyticsService {
-
- public LargeDataResponse getLargeDataset(@OpenApiParam("datasetId") String id) {
- MessageContext msgCtx = MessageContext.getCurrentMessageContext();
- msgCtx.setProperty(Constants.Configuration.TRANSPORT_NAME, "h2");
-
- // HTTP/2 optimizes large response delivery
- return dataProcessor.generateLargeDataset(id);
- }
-}
-</pre>
-
-<h2>Enterprise WildFly Integration</h2>
-
-<div style="background-color: #f0f8ff; border: 1px solid #0066cc; padding: 10px; margin: 10px 0;">
-<strong>🏢 WildFly Integration:</strong> Axis2 provides deep integration with WildFly's Undertow HTTP/2
-implementation, delivering cooperative optimization through aligned buffer management and connection pooling.
-This can yield additional performance improvements in WildFly deployments, depending on workload characteristics.
-</div>
-
-<h3>WildFly HTTP/2 Configuration</h3>
-
-<p>Configure WildFly Undertow for optimal OpenAPI + HTTP/2 performance:</p>
-
-<pre>
-<!-- standalone.xml - WildFly HTTP/2 + OpenAPI Optimization -->
-<subsystem xmlns="urn:jboss:domain:undertow:14.0">
-
- <!-- Optimized Buffer Pool for Large OpenAPI Specs -->
- <byte-buffer-pool name="default"
- buffer-size="65536" <!-- 64KB aligned with HTTP/2 frames -->
- max-pool-size="512" <!-- Support concurrent API requests -->
- direct="true"/>
-
- <server name="default-server">
- <!-- HTTP/2 + HTTPS Listener for OpenAPI -->
- <https-listener name="https"
- socket-binding="https"
- ssl-context="applicationSSC"
- enable-http2="true"
- max-post-size="104857600" <!-- 100MB for large API requests -->
- http2-enable-push="false" <!-- Optimize for REST APIs -->
- http2-header-table-size="8192" <!-- Optimize for OpenAPI headers -->
- http2-initial-window-size="131072" <!-- 128KB for large responses -->
- http2-max-concurrent-streams="75" <!-- Concurrent API calls -->
- http2-max-frame-size="65536"/> <!-- 64KB frame size -->
- </server>
-</subsystem>
-</pre>
-
-<h3>Application Deployment</h3>
-
-<p>Deploy your OpenAPI-enabled application with HTTP/2 optimization:</p>
-
-<pre>
-<!-- web.xml - HTTP/2 + OpenAPI Application -->
-<web-app xmlns="https://jakarta.ee/xml/ns/jakartaee"
- xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
- xsi:schemaLocation="https://jakarta.ee/xml/ns/jakartaee
- https://jakarta.ee/xml/ns/jakartaee/web-app_5_0.xsd"
- version="5.0">
-
- <display-name>High-Performance OpenAPI + HTTP/2 Service</display-name>
-
- <!-- Axis2 Servlet (HTTP/2 is configured in axis2.xml, not here) -->
- <servlet>
- <servlet-name>AxisServlet</servlet-name>
- <servlet-class>org.apache.axis2.transport.http.AxisServlet</servlet-class>
- <load-on-startup>1</load-on-startup>
- </servlet>
-
- <!-- OpenAPI Endpoints -->
- <servlet-mapping>
- <servlet-name>AxisServlet</servlet-name>
- <url-pattern>/services/*</url-pattern>
- </servlet-mapping>
-
-</web-app>
-</pre>
-
-<h2>Enterprise Tomcat 11 Integration</h2>
-
-<div style="background-color: #f8f4e6; border: 1px solid #ff9800; padding: 10px; margin: 10px 0;">
-<strong>🚀 Tomcat 11 Benefits:</strong> Apache Tomcat 11 provides excellent HTTP/2 + OpenAPI integration
-with streamlined configuration and optimized performance. Tomcat's native HTTP/2 implementation delivers
-low overhead and simplified deployment, making it an excellent choice for high-performance OpenAPI services.
-</div>
-
-<h3>Tomcat 11 vs WildFly for HTTP/2 + OpenAPI</h3>
-
-<table border="1">
-<tr><th>Aspect</th><th>Tomcat 11</th><th>WildFly 32</th><th>Advantage</th></tr>
-<tr><td><strong>Configuration Complexity</strong></td><td>~15 lines (server.xml)</td><td>~150 lines (standalone.xml)</td><td><strong>Tomcat</strong>: 90% simpler</td></tr>
-<tr><td><strong>HTTP/2 Performance</strong></td><td>Lightweight, low-overhead HTTP/2</td><td>Full Jakarta EE HTTP/2 stack</td><td>Depends on workload</td></tr>
-<tr><td><strong>Memory Usage</strong></td><td>30% lower baseline memory</td><td>Higher JEE overhead</td><td><strong>Tomcat</strong>: More efficient</td></tr>
-<tr><td><strong>SSL Setup Time</strong></td><td>2-5 minutes</td><td>15-30 minutes</td><td><strong>Tomcat</strong>: 6x faster setup</td></tr>
-<tr><td><strong>OpenAPI Integration</strong></td><td>Zero classloader conflicts</td><td>Complex module system</td><td><strong>Tomcat</strong>: Seamless deployment</td></tr>
-<tr><td><strong>HTTP/2 Streams</strong></td><td>200+ concurrent streams</td><td>75-100 typical streams</td><td><strong>Tomcat</strong>: Higher concurrency</td></tr>
-</table>
-
-<h3>Tomcat 11 HTTP/2 + OpenAPI Configuration</h3>
-
-<p>Production-optimized Tomcat configuration for maximum HTTP/2 + OpenAPI performance:</p>
-
-<pre>
-<!-- server.xml - Tomcat 11 HTTP/2 + OpenAPI Optimization -->
-<Server port="8005" shutdown="SHUTDOWN">
-
- <!-- HTTP/2 Optimized Thread Pool -->
- <Service name="Catalina">
- <Executor name="tomcatThreadPool"
- namePrefix="catalina-exec-"
- maxThreads="200" <!-- Match HTTP/2 concurrent streams -->
- minSpareThreads="25"
- maxIdleTime="300000" <!-- 5 minutes -->
- prestartminSpareThreads="true" />
-
- <!-- HTTP Connector with HTTP/2 Upgrade -->
- <Connector executor="tomcatThreadPool"
- port="8080"
- protocol="HTTP/1.1"
- redirectPort="8443"
- maxPostSize="104857600" <!-- 100MB for large OpenAPI payloads -->
- connectionTimeout="300000" <!-- 5 minutes for large spec generation -->
- keepAliveTimeout="300000" <!-- Persistent connections -->
- maxKeepAliveRequests="1000" <!-- High keep-alive for performance -->
- compression="on" <!-- JSON compression -->
- compressionMinSize="2048" <!-- Compress >2KB OpenAPI specs -->
- compressableMimeType="application/json,application/xml,text/html" />
-
- <!-- HTTPS + HTTP/2 Connector (Production Optimized) -->
- <Connector executor="tomcatThreadPool"
- port="8443"
- protocol="org.apache.coyote.http11.Http11AprProtocol"
- maxPostSize="104857600" <!-- 100MB for large API requests -->
- SSLEnabled="true"
- scheme="https"
- secure="true"
- connectionTimeout="300000" <!-- 5 minutes -->
- keepAliveTimeout="300000" <!-- Persistent connections -->
-
- <!-- HTTP/2 Specific Configuration -->
- upgradeAsyncTimeout="300000" <!-- HTTP/2 upgrade timeout -->
- http2MaxConcurrentStreams="200" <!-- High concurrency for enterprise workloads -->
- http2InitialWindowSize="131072" <!-- 128KB - optimized for large payloads -->
- http2MaxFrameSize="65536" <!-- 64KB - aligned with buffer management -->
- http2MaxHeaderTableSize="8192" <!-- 8KB header table -->
- http2MaxHeaderListSize="32768" <!-- 32KB header list -->
- http2EnablePush="false" <!-- Disabled for OpenAPI services -->
-
- <!-- SSL Configuration -->
- SSLCertificateFile="/opt/tomcat11/ssl/certificate.crt"
- SSLCertificateKeyFile="/opt/tomcat11/ssl/private.key"
- SSLCertificateChainFile="/opt/tomcat11/ssl/chain.crt"
- SSLProtocol="TLSv1.2+TLSv1.3" <!-- Modern TLS for HTTP/2 -->
- SSLCipherSuite="ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384"
- SSLHonorCipherOrder="true"
-
- <!-- OpenAPI JSON Optimization -->
- compression="on"
- compressionMinSize="2048"
- compressableMimeType="application/json,application/xml" />
-
- <!-- Host with HTTP/2 + OpenAPI Access Logging -->
- <Engine name="Catalina" defaultHost="localhost">
- <Host name="localhost" appBase="webapps" unpackWARs="true" autoDeploy="true">
-
- <!-- HTTP/2 + OpenAPI Performance Logging -->
- <Valve className="org.apache.catalina.valves.AccessLogValve"
- directory="logs"
- prefix="openapi_http2_access"
- suffix=".log"
- pattern="%h %u %t &quot;%r&quot; %s %b %D Protocol:%{org.apache.coyote.request.protocol}r OpenAPI-Size:%{Content-Length}o Streams:%{http2.concurrent.streams}r Time:%T"
- resolveHosts="false" />
-
- </Host>
- </Engine>
- </Service>
-</Server>
-</pre>
-
-<h3>Enhanced Axis2 Configuration for Tomcat HTTP/2</h3>
-
-<p>Optimize axis2.xml specifically for Tomcat 11's HTTP/2 implementation:</p>
-
-<pre>
-<!-- axis2.xml - Tomcat 11 + HTTP/2 + OpenAPI Optimized Configuration -->
-<axisconfig name="AxisJava2.0-Tomcat11-HTTP2-OpenAPI">
-
- <!-- HTTP/2 is negotiated by the transport sender below.
- Tomcat's HTTP/2 connector (h2c/h2) is configured in server.xml,
- not in axis2.xml. No Tomcat-specific or OpenAPI-specific
- parameters are needed here. -->
-
- <!-- HTTP/2 Transport Sender -->
- <transportSender name="h2"
- class="org.apache.axis2.transport.h2.impl.httpclient5.H2TransportSender">
- <parameter name="PROTOCOL">HTTP/2.0</parameter>
-
- <!-- Tomcat HTTP/2 Coordination -->
- <parameter name="maxConcurrentStreams">200</parameter> <!-- Matches Tomcat config -->
- <parameter name="initialWindowSize">131072</parameter> <!-- 128KB - matches Tomcat -->
- <parameter name="maxFrameSize">65536</parameter> <!-- 64KB - matches Tomcat -->
- <parameter name="maxConnectionsTotal">50</parameter>
- <parameter name="maxConnectionsPerRoute">15</parameter> <!-- Higher than WildFly -->
- <parameter name="connectionTimeout">60000</parameter> <!-- 1 minute -->
- <parameter name="responseTimeout">300000</parameter> <!-- 5 minutes -->
-
- <!-- Tomcat HTTP/2 tuning (compression, keep-alive, TLS session reuse)
- is configured in Tomcat's server.xml, not here. -->
- </transportSender>
-
-</axisconfig>
-</pre>
-
-<h3>Production Tomcat Deployment</h3>
-
-<p>Complete production deployment configuration:</p>
-
-<pre>
-<!-- web.xml - Tomcat HTTP/2 + OpenAPI Application -->
-<web-app xmlns="https://jakarta.ee/xml/ns/jakartaee"
- xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
- xsi:schemaLocation="https://jakarta.ee/xml/ns/jakartaee
- https://jakarta.ee/xml/ns/jakartaee/web-app_5_0.xsd"
- version="5.0">
-
- <display-name>Enterprise OpenAPI + HTTP/2 on Tomcat 11</display-name>
-
- <!-- HTTP/2 and streaming are configured in axis2.xml via message receiver
- and formatter class selection, not via web.xml context-params.
- See the axis2.xml HTTP/2 transport configuration section. -->
-
- <!-- Axis2 Servlet -->
- <servlet>
- <servlet-name>AxisServlet</servlet-name>
- <servlet-class>org.apache.axis2.transport.http.AxisServlet</servlet-class>
- <load-on-startup>1</load-on-startup>
- <async-supported>true</async-supported>
- </servlet>
-
- <servlet-mapping>
- <servlet-name>AxisServlet</servlet-name>
- <url-pattern>/services/*</url-pattern>
- </servlet-mapping>
-
-</web-app>
-</pre>
-
-<h3>JVM Optimization for Tomcat + HTTP/2 + OpenAPI</h3>
-
-<p>Optimize JVM settings specifically for Tomcat HTTP/2 + OpenAPI performance:</p>
-
-<pre>
-# catalina.sh - Production JVM Settings for HTTP/2 + OpenAPI
-export CATALINA_OPTS="$CATALINA_OPTS -Xms2048m -Xmx4096m"
-export CATALINA_OPTS="$CATALINA_OPTS -XX:+UseG1GC"
-export CATALINA_OPTS="$CATALINA_OPTS -XX:MaxGCPauseMillis=200"
-export CATALINA_OPTS="$CATALINA_OPTS -XX:G1HeapRegionSize=16m"
-
-# HTTP/2 Connection Pool Optimization
-export CATALINA_OPTS="$CATALINA_OPTS -Djava.net.preferIPv6Addresses=false"
-export CATALINA_OPTS="$CATALINA_OPTS -Dorg.apache.coyote.http2.Http2Protocol.maxConcurrentStreams=200"
-export CATALINA_OPTS="$CATALINA_OPTS -Dorg.apache.coyote.http2.Http2Protocol.initialWindowSize=131072"
-
-# Note: Axis2 HTTP/2 and OpenAPI are configured in axis2.xml, not via
-# system properties. No -Daxis2.* flags are needed.
-
-# For production monitoring, use Micrometer with Prometheus/Grafana
-# or Spring Boot Actuator endpoints rather than raw JMX.
-</pre>
-
-</body>
-</html>
diff --git a/src/site/xdoc/docs/toc.xml b/src/site/xdoc/docs/toc.xml
index 336714f0dc..1f5299472a 100644
--- a/src/site/xdoc/docs/toc.xml
+++ b/src/site/xdoc/docs/toc.xml
@@ -61,8 +61,7 @@ Guide</a></li>
<li>7.3 <a href="openapi-rest-userguide.html#Sample_Services_Overview">Complete Sample Application</a></li>
<li>7.4 <a href="openapi-rest-userguide.html#Interactive_Swagger_UI">Interactive Swagger UI</a></li>
<li>7.5 <a href="openapi-rest-advanced-userguide.html">Advanced Enterprise OpenAPI Features</a></li>
-<li>7.6 <a href="openapi-rest-advanced-http2-userguide.html">OpenAPI + HTTP/2 Performance Integration</a></li>
-<li>7.7 <a href="openapi-jpa-schema.html">JPA/Hibernate Schema Generation</a>
+<li>7.6 <a href="openapi-jpa-schema.html">JPA/Hibernate Schema Generation</a>
<ul>
<li>7.7.1 <a href="openapi-jpa-schema.html#annotation_mode">JPA Annotation Mode (@Entity, @Column, @ManyToOne)</a></li>
<li>7.7.2 <a href="openapi-jpa-schema.html#hbm_xml_mode">Hibernate XML Mapping Mode (.hbm.xml)</a></li>
@@ -160,7 +159,6 @@ Support</a></li>
<li><a href="openapi-rest-userguide.html#Sample_Services_Overview">Complete JSON REST API Examples</a></li>
<li><a href="openapi-rest-userguide.html#Interactive_Swagger_UI">Interactive API Testing with Swagger UI</a></li>
<li><a href="openapi-rest-advanced-userguide.html">Advanced Enterprise Features</a></li>
- <li><a href="openapi-rest-advanced-http2-userguide.html">HTTP/2 Performance Integration</a></li>
</ul>
</li>
<li><strong>23.4 <a href="json-rpc-mcp-guide.html">JSON-RPC MCP Integration Guide</a></strong>
(axis-axis2-java-core) 02/02: docs: Add JPA schema generation and pagination guides
Posted by ro...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
robertlazarski pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/axis-axis2-java-core.git
commit 78234f36a89ebebc8f7232ff1b090fd317fe7101
Author: Robert Lazarski <ro...@gmail.com>
AuthorDate: Mon May 11 10:59:53 2026 -1000
docs: Add JPA schema generation and pagination guides
Two xdoc documentation files for implemented features that had
TOC entries but no docs:
openapi-jpa-schema.xml — Documents the axis2-jpa-schema module:
- JPA annotation introspection (@Entity, @Column, @Id, etc.)
- Hibernate XML mapping introspection (.hbm.xml)
- Read vs Write schema generation (write excludes @GeneratedValue,
@Version, custom audit annotations)
- Custom write-exclude annotation registration
- Relationship $ref convention for OpenAPI components
- Type mapping tables for both annotation and HBM XML modes
- 28 tests documented
json-pagination.xml — Documents PaginatedResponse<T> and
PaginationRequest:
- Wire format with pagination metadata (offset, limit,
totalCount, hasMore)
- Service integration pattern (DAO offset/limit)
- Safety: maxLimit clamping, negative offset handling
- Frontend patterns: page controls, virtual scroll, SmartClient
- Why offset/limit instead of cursor
- 20 tests documented
Also fixed:
- TOC numbering (7.7.x → 7.6.x for JPA schema subsections)
- json-rpc-mcp-guide.xml: updated pagination from "not implemented"
to "offset/limit implemented" with link to new guide
Co-Authored-By: Claude Opus 4.6 (1M context) <no...@anthropic.com>
---
src/site/xdoc/docs/json-pagination.xml | 172 ++++++++++++++++++++++++
src/site/xdoc/docs/json-rpc-mcp-guide.xml | 10 +-
src/site/xdoc/docs/openapi-jpa-schema.xml | 211 ++++++++++++++++++++++++++++++
src/site/xdoc/docs/toc.xml | 10 +-
4 files changed, 393 insertions(+), 10 deletions(-)
diff --git a/src/site/xdoc/docs/json-pagination.xml b/src/site/xdoc/docs/json-pagination.xml
new file mode 100644
index 0000000000..5a09d5aeb7
--- /dev/null
+++ b/src/site/xdoc/docs/json-pagination.xml
@@ -0,0 +1,172 @@
+<!--
+ ~ Licensed to the Apache Software Foundation (ASF) under one
+ ~ or more contributor license agreements. See the NOTICE file
+ ~ distributed with this work for additional information
+ ~ regarding copyright ownership. The ASF licenses this file
+ ~ to you under the Apache License, Version 2.0 (the
+ ~ "License"); you may not use this file except in compliance
+ ~ with the License. You may obtain a copy of the License at
+ ~
+ ~ http://www.apache.org/licenses/LICENSE-2.0
+ ~
+ ~ Unless required by applicable law or agreed to in writing,
+ ~ software distributed under the License is distributed on an
+ ~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ ~ KIND, either express or implied. See the License for the
+ ~ specific language governing permissions and limitations
+ ~ under the License.
+ -->
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml">
+<head><title>Offset/Limit Pagination for JSON-RPC Services</title></head>
+<body>
+
+<h1 id="overview">Offset/Limit Pagination for JSON-RPC Services</h1>
+
+<p>Axis2 provides a generic pagination framework for JSON-RPC services
+backed by SQL databases. The two classes —
+<code>PaginationRequest</code> and <code>PaginatedResponse<T></code> —
+map directly to JPA/Hibernate's <code>setFirstResult(offset)</code> and
+<code>setMaxResults(limit)</code> pattern.</p>
+
+<p><strong>Package:</strong> <code>org.apache.axis2.json.rpc</code></p>
+
+<h2 id="wire_format">Wire Format</h2>
+
+<p>A paginated response wraps the result list with metadata:</p>
+
+<pre>
+{
+ "response": {
+ "data": [ ... ],
+ "pagination": {
+ "offset": 0,
+ "limit": 50,
+ "totalCount": 1247,
+ "hasMore": true
+ }
+ }
+}
+</pre>
+
+<ul>
+ <li><strong>offset</strong> — zero-based index of the first item in this page</li>
+ <li><strong>limit</strong> — maximum items requested (page size)</li>
+ <li><strong>totalCount</strong> — total items matching the query across all pages</li>
+ <li><strong>hasMore</strong> — true when <code>offset + limit < totalCount</code></li>
+</ul>
+
+<h2 id="service_integration">Service Integration</h2>
+
+<p>A typical service method delegates offset/limit to the DAO:</p>
+
+<pre>
+public PaginatedResponse<AssetBO> findAssets(AssetQuery query) {
+ List<AssetBO> items = dao.findList(query.getOffset(), query.getLimit());
+ long total = dao.count(query);
+ return PaginatedResponse.of(items, query.getOffset(), query.getLimit(), total);
+}
+</pre>
+
+<p>The request POJO can embed <code>PaginationRequest</code> fields directly
+or accept them as separate parameters:</p>
+
+<pre>
+// Client sends:
+{
+ "searchTerm": "AAPL",
+ "offset": 100,
+ "limit": 50
+}
+</pre>
+
+<h3>Unpaginated Responses</h3>
+
+<p>For small lookup tables (e.g., a list of 15 departments), use the
+convenience factory to wrap the full list with <code>hasMore=false</code>:</p>
+
+<pre>
+return PaginatedResponse.unpaginated(departments);
+// → offset=0, limit=15, totalCount=15, hasMore=false
+</pre>
+
+<h2 id="safety">Safety: maxLimit Clamping and Input Validation</h2>
+
+<p><code>PaginationRequest</code> enforces safety constraints at the getter level:</p>
+
+<table border="1">
+<tr><th>Input</th><th>Behavior</th></tr>
+<tr><td><code>offset < 0</code></td><td>Clamped to 0</td></tr>
+<tr><td><code>limit <= 0</code></td><td>Default: 50</td></tr>
+<tr><td><code>limit > maxLimit</code></td><td>Capped at maxLimit (default: 2000)</td></tr>
+</table>
+
+<p>Services that handle expensive entities can lower the cap per-operation:</p>
+
+<pre>
+// Large text fields — cap at 100 per page
+request.setMaxLimit(100);
+int safeLimit = request.getLimit(); // capped at 100
+</pre>
+
+<h2 id="frontend_patterns">Frontend Patterns</h2>
+
+<h3>Page Controls ("Showing 151–200 of 1,247")</h3>
+<pre>
+// JavaScript / TypeScript
+const { offset, limit, totalCount } = pagination;
+const currentPage = Math.floor(offset / limit) + 1;
+const totalPages = Math.ceil(totalCount / limit);
+const showingFrom = offset + 1;
+const showingTo = offset + data.length;
+</pre>
+
+<h3>Virtual Scroll / Infinite Scroll</h3>
+<pre>
+// Load next chunk when user scrolls
+const nextOffset = pagination.offset + pagination.limit;
+if (pagination.hasMore) {
+ fetchPage(nextOffset, pagination.limit);
+}
+</pre>
+
+<h3>SmartClient startRow/endRow</h3>
+<pre>
+// SmartClient sends startRow=300, endRow=350
+// Service translates: offset = startRow, limit = endRow - startRow
+int offset = startRow;
+int limit = endRow - startRow;
+</pre>
+
+<h2>Why Offset/Limit Instead of Cursor</h2>
+
+<ul>
+ <li><strong>DAO compatibility</strong> — existing Hibernate/JPA DAOs use
+ <code>query.setFirstResult(offset)</code> and <code>query.setMaxResults(limit)</code>.
+ Cursor pagination requires a stable sort key and stateful server-side tokens.</li>
+ <li><strong>Frontend grids</strong> — SmartClient, AG Grid, and React Table natively
+ speak offset/limit via <code>startRow</code>/<code>endRow</code> or
+ <code>page</code>/<code>pageSize</code>.</li>
+ <li><strong>totalCount</strong> — enables "Showing 1–50 of 1,247" UI patterns
+ and page-count calculations. Cursor APIs typically omit total counts because
+ they are expensive for the cursor model, but they are cheap when the DAO
+ already runs <code>SELECT COUNT(*)</code>.</li>
+</ul>
+
+<h2>Test Coverage</h2>
+
+<p>The <code>PaginatedResponseTest</code> class provides 20 tests covering:</p>
+<ul>
+ <li>First page, last page, partial last page, single page, empty result</li>
+ <li>Null data treated as empty list</li>
+ <li>Unpaginated convenience factory</li>
+ <li>Negative offset clamping, zero/negative limit defaults, maxLimit enforcement</li>
+ <li>Enterprise scenarios: 8,543-item virtual scroll, soft-delete filtering,
+ service-specific maxLimit, SmartClient startRow/endRow translation</li>
+ <li>Request → response round-trip simulation</li>
+</ul>
+
+</body>
+</html>
diff --git a/src/site/xdoc/docs/json-rpc-mcp-guide.xml b/src/site/xdoc/docs/json-rpc-mcp-guide.xml
index 7a73c1bdc7..a0f8b6d173 100644
--- a/src/site/xdoc/docs/json-rpc-mcp-guide.xml
+++ b/src/site/xdoc/docs/json-rpc-mcp-guide.xml
@@ -602,9 +602,11 @@ Each item notes whether the gap is architectural (won't be added to Axis2) or de
<td>When set to <code>ServiceName/operationName</code>, <code>_meta.tickerResolveEndpoint</code> is added to the catalog. Omitted entirely when not configured so deployments without a ticker service are unaffected.</td>
</tr>
<tr>
- <td>Cursor-based pagination</td>
- <td>Not implemented</td>
- <td>Axis2 operations return their full result sets. Cursor-based pagination would need to be implemented in a separate REST layer.</td>
+ <td>Pagination</td>
+ <td><strong>Offset/limit implemented</strong> — see <a href="json-pagination.html">Pagination Guide</a></td>
+ <td>Axis2 provides <code>PaginatedResponse<T></code> and <code>PaginationRequest</code>
+ for offset/limit pagination with maxLimit clamping.
+ Cursor-based pagination is not implemented (offset/limit maps directly to JPA/Hibernate DAO patterns).</td>
</tr>
<tr>
<td>RFC 7807 Problem Details error format</td>
@@ -638,7 +640,7 @@ uses determines what limitations apply:</p>
<tr><td>Auth</td><td>email + password → Bearer token (loginService)</td><td>API key + secret → scoped JWT</td></tr>
<tr><td>Query semantics</td><td>Per-operation parameters in arg0</td><td>Uniform filter/sort/fields on every resource</td></tr>
<tr><td>Error format</td><td>SOAP fault with correlation ID UUID</td><td>RFC 7807 Problem Details (JSON, per-field)</td></tr>
-<tr><td>Pagination</td><td>Full result sets only</td><td>Cursor-based</td></tr>
+<tr><td>Pagination</td><td>Offset/limit (<a href="json-pagination.html">PaginatedResponse</a>)</td><td>Cursor-based</td></tr>
<tr><td>inputSchema</td><td>Full JSON Schema via <code>mcpInputSchema</code> in services.xml (hand-authored)</td><td>Full JSON Schema from OpenAPI annotations (auto-generated)</td></tr>
</table>
diff --git a/src/site/xdoc/docs/openapi-jpa-schema.xml b/src/site/xdoc/docs/openapi-jpa-schema.xml
new file mode 100644
index 0000000000..badb7c6c04
--- /dev/null
+++ b/src/site/xdoc/docs/openapi-jpa-schema.xml
@@ -0,0 +1,211 @@
+<!--
+ ~ Licensed to the Apache Software Foundation (ASF) under one
+ ~ or more contributor license agreements. See the NOTICE file
+ ~ distributed with this work for additional information
+ ~ regarding copyright ownership. The ASF licenses this file
+ ~ to you under the Apache License, Version 2.0 (the
+ ~ "License"); you may not use this file except in compliance
+ ~ with the License. You may obtain a copy of the License at
+ ~
+ ~ http://www.apache.org/licenses/LICENSE-2.0
+ ~
+ ~ Unless required by applicable law or agreed to in writing,
+ ~ software distributed under the License is distributed on an
+ ~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ ~ KIND, either express or implied. See the License for the
+ ~ specific language governing permissions and limitations
+ ~ under the License.
+ -->
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml">
+<head><title>JPA/Hibernate Schema Generation for OpenAPI</title></head>
+<body>
+
+<h1>JPA/Hibernate Schema Generation for OpenAPI</h1>
+
+<p>The <code>axis2-jpa-schema</code> module generates JSON Schema definitions
+from JPA annotations or Hibernate XML mappings (<code>.hbm.xml</code>).
+These schemas can be embedded in OpenAPI 3.0 specifications to document
+request/response bodies that map directly to database entities.</p>
+
+<p><strong>Module:</strong> <code>modules/jpa-schema</code><br/>
+<strong>Package:</strong> <code>org.apache.axis2.jpa.schema</code></p>
+
+<h2 id="annotation_mode">JPA Annotation Mode</h2>
+
+<p>The <code>AnnotationIntrospector</code> reads standard Jakarta Persistence
+annotations (<code>@Entity</code>, <code>@Column</code>, <code>@Id</code>,
+<code>@ManyToOne</code>, <code>@OneToMany</code>, etc.) and produces an
+<code>EntitySchemaModel</code> that the <code>JpaSchemaGenerator</code>
+converts to JSON Schema.</p>
+
+<h3>Supported Annotations</h3>
+
+<table border="1">
+<tr><th>Annotation</th><th>Schema Effect</th></tr>
+<tr><td><code>@Entity</code></td><td>Entity is eligible for introspection</td></tr>
+<tr><td><code>@Table(name="...")</code></td><td>Recorded in schema description</td></tr>
+<tr><td><code>@Id</code></td><td>Marked as required; <code>readOnly=true</code> in read schema</td></tr>
+<tr><td><code>@GeneratedValue</code></td><td>Excluded from write schema (server-managed)</td></tr>
+<tr><td><code>@Column(nullable, length)</code></td><td>Maps to <code>required</code> and <code>maxLength</code></td></tr>
+<tr><td><code>@Version</code></td><td>Excluded from write schema (server-managed)</td></tr>
+<tr><td><code>@Transient</code></td><td>Excluded from all schemas</td></tr>
+<tr><td><code>@Enumerated(STRING)</code></td><td>Emitted as <code>{"type":"string","enum":[...]}</code></td></tr>
+<tr><td><code>@ManyToOne</code></td><td>Emitted as <code>{"$ref":"#/components/schemas/Entity"}</code></td></tr>
+<tr><td><code>@OneToMany</code></td><td>Emitted as <code>{"type":"array","items":{"$ref":"..."}}</code></td></tr>
+</table>
+
+<h3>Example</h3>
+
+<pre>
+@Entity
+@Table(name = "PRODUCT")
+public class Product {
+
+ @Id
+ @GeneratedValue(strategy = GenerationType.IDENTITY)
+ private BigDecimal productID;
+
+ @Column(nullable = false, length = 200)
+ private String name;
+
+ @Enumerated(EnumType.STRING)
+ private ProductStatus status;
+
+ @Version
+ private Long objVersion;
+
+ @ManyToOne
+ private Department department;
+
+ @OneToMany
+ private List<LineItem> lineItems;
+}
+</pre>
+
+<pre>
+AnnotationIntrospector introspector = new AnnotationIntrospector();
+EntitySchemaModel model = introspector.introspect(Product.class);
+ObjectNode readSchema = JpaSchemaGenerator.generateReadSchema(model);
+ObjectNode writeSchema = JpaSchemaGenerator.generateWriteSchema(model);
+</pre>
+
+<h2 id="read_write_schemas">Read vs Write Schema Generation</h2>
+
+<p>The generator produces two schema variants per entity:</p>
+
+<table border="1">
+<tr><th>Variant</th><th>Includes</th><th>Use Case</th></tr>
+<tr><td><strong>Read schema</strong></td><td>All fields (IDs as <code>readOnly</code>)</td><td>GET response bodies</td></tr>
+<tr><td><strong>Write schema</strong></td><td>Excludes <code>@GeneratedValue</code> IDs, <code>@Version</code>, and custom audit fields</td><td>POST/PUT request bodies</td></tr>
+</table>
+
+<p>The <code>generateBothSchemas()</code> method returns both at once:</p>
+<pre>
+Map<String, ObjectNode> schemas = JpaSchemaGenerator.generateBothSchemas(model);
+// "Product" → read schema
+// "ProductWrite" → write schema
+</pre>
+
+<h3>What Gets Excluded from Write</h3>
+<ul>
+ <li><code>@Id @GeneratedValue</code> — server assigns the ID</li>
+ <li><code>@Version</code> — server manages optimistic locking</li>
+ <li><code>@Transient</code> — excluded from both read and write</li>
+ <li>Custom annotations (see below)</li>
+</ul>
+
+<h2 id="custom_annotations">Custom Audit Annotation Support</h2>
+
+<p>Many enterprise codebases have project-specific annotations that mark
+fields as server-managed (e.g., <code>@IgnoreChanges</code> for audit
+timestamps, <code>@CreatedBy</code>, <code>@LastModifiedDate</code>).
+Register these with the introspector to exclude them from write schemas:</p>
+
+<pre>
+AnnotationIntrospector introspector = new AnnotationIntrospector();
+introspector.addWriteExcludeAnnotation("com.example.IgnoreChanges");
+introspector.addWriteExcludeAnnotation("com.example.audit.CreatedBy");
+
+EntitySchemaModel model = introspector.introspect(Product.class);
+// Fields annotated with @IgnoreChanges or @CreatedBy are now
+// excluded from the write schema but present in the read schema.
+</pre>
+
+<h2 id="hbm_xml_mode">Hibernate XML Mapping Mode (.hbm.xml)</h2>
+
+<p>For codebases that use Hibernate XML mappings instead of (or alongside)
+JPA annotations, the <code>HbmXmlIntrospector</code> parses <code>.hbm.xml</code>
+files and produces the same <code>EntitySchemaModel</code>:</p>
+
+<pre>
+HbmXmlIntrospector introspector = new HbmXmlIntrospector();
+try (InputStream is = getClass().getResourceAsStream("/DepartmentBO.hbm.xml")) {
+ EntitySchemaModel model = introspector.introspect(is, "DepartmentBO.hbm.xml");
+ ObjectNode readSchema = JpaSchemaGenerator.generateReadSchema(model);
+}
+</pre>
+
+<h3>Supported HBM XML Elements</h3>
+
+<table border="1">
+<tr><th>HBM XML Element</th><th>Schema Effect</th></tr>
+<tr><td><code><id></code> with <code><generator></code></td><td>Required, <code>readOnly</code>, excluded from write</td></tr>
+<tr><td><code><version></code></td><td>Excluded from write schema</td></tr>
+<tr><td><code><property></code></td><td>Mapped by Hibernate type → JSON Schema type</td></tr>
+<tr><td><code><many-to-one></code></td><td><code>$ref</code> to referenced entity</td></tr>
+<tr><td><code><set></code> / <code><list></code></td><td>Array of <code>$ref</code></td></tr>
+<tr><td><code><component></code></td><td>Flattened with dot-notation prefix (e.g., <code>address.city</code>)</td></tr>
+<tr><td>Nested <code><column not-null="true"></code></td><td>Maps to required</td></tr>
+</table>
+
+<h3>Type Mapping</h3>
+
+<table border="1">
+<tr><th>Hibernate / Java Type</th><th>JSON Schema</th></tr>
+<tr><td><code>string</code>, <code>text</code></td><td><code>{"type":"string"}</code></td></tr>
+<tr><td><code>integer</code>, <code>int</code></td><td><code>{"type":"integer","format":"int32"}</code></td></tr>
+<tr><td><code>long</code>, <code>big_integer</code></td><td><code>{"type":"integer","format":"int64"}</code></td></tr>
+<tr><td><code>double</code>, <code>float</code>, <code>big_decimal</code></td><td><code>{"type":"number"}</code></td></tr>
+<tr><td><code>boolean</code>, <code>yes_no</code></td><td><code>{"type":"boolean"}</code></td></tr>
+<tr><td><code>timestamp</code>, <code>date</code></td><td><code>{"type":"string","format":"date-time"}</code></td></tr>
+</table>
+
+<h2>Test Coverage</h2>
+
+<p>The <code>JpaSchemaGeneratorTest</code> class provides comprehensive tests:</p>
+<ul>
+ <li><strong>Annotation introspection</strong> (12 tests): entity detection, ID fields,
+ column constraints, version, transient, enums, ManyToOne, OneToMany,
+ custom write-exclude annotations</li>
+ <li><strong>Schema generation</strong> (6 tests): read includes all fields, write excludes
+ server-managed fields, required array, relationship $refs, enum values,
+ generateBothSchemas</li>
+ <li><strong>HBM XML introspection</strong> (10 tests): parses CompanyBO and DepartmentBO
+ (70+ field production-grade entity), verifies type mapping, relationships,
+ collections, component flattening, nested column not-null</li>
+</ul>
+
+<h2>Relationship $ref Convention</h2>
+
+<p>Relationships are emitted as <code>$ref</code> pointers using the OpenAPI
+components convention:</p>
+
+<pre>
+// ManyToOne
+{"$ref": "#/components/schemas/Department"}
+
+// OneToMany
+{"type": "array", "items": {"$ref": "#/components/schemas/LineItem"}}
+
+// Write schema uses "Write" suffix
+{"$ref": "#/components/schemas/DepartmentWrite"}
+</pre>
+
+<p>The caller is responsible for ensuring that referenced entity schemas
+are also generated and added to the OpenAPI components section.</p>
+
+</body>
+</html>
diff --git a/src/site/xdoc/docs/toc.xml b/src/site/xdoc/docs/toc.xml
index 1f5299472a..14c8f5e94d 100644
--- a/src/site/xdoc/docs/toc.xml
+++ b/src/site/xdoc/docs/toc.xml
@@ -63,10 +63,10 @@ Guide</a></li>
<li>7.5 <a href="openapi-rest-advanced-userguide.html">Advanced Enterprise OpenAPI Features</a></li>
<li>7.6 <a href="openapi-jpa-schema.html">JPA/Hibernate Schema Generation</a>
<ul>
-<li>7.7.1 <a href="openapi-jpa-schema.html#annotation_mode">JPA Annotation Mode (@Entity, @Column, @ManyToOne)</a></li>
-<li>7.7.2 <a href="openapi-jpa-schema.html#hbm_xml_mode">Hibernate XML Mapping Mode (.hbm.xml)</a></li>
-<li>7.7.3 <a href="openapi-jpa-schema.html#read_write_schemas">Read vs Write Schema Generation</a></li>
-<li>7.7.4 <a href="openapi-jpa-schema.html#custom_annotations">Custom Audit Annotation Support</a></li>
+<li>7.6.1 <a href="openapi-jpa-schema.html#annotation_mode">JPA Annotation Mode (@Entity, @Column, @ManyToOne)</a></li>
+<li>7.6.2 <a href="openapi-jpa-schema.html#hbm_xml_mode">Hibernate XML Mapping Mode (.hbm.xml)</a></li>
+<li>7.6.3 <a href="openapi-jpa-schema.html#read_write_schemas">Read vs Write Schema Generation</a></li>
+<li>7.6.4 <a href="openapi-jpa-schema.html#custom_annotations">Custom Audit Annotation Support</a></li>
</ul>
</li>
</ul>
@@ -171,8 +171,6 @@ Support</a></li>
<li><a href="json-rpc-mcp-guide.html#tested_features">Unit Test Feature Coverage</a></li>
<li><a href="json-rpc-mcp-guide.html#not_implemented">Not Implemented / Limitations</a></li>
<li><a href="json-streaming-formatter.html">Streaming Formatter for Large MCP Tool Responses</a></li>
- <!-- data_api_relationship anchor removed from guide; link to top-level page -->
- <li><a href="json-rpc-mcp-guide.html">Relationship to Data API Vision</a></li>
<li><a href="json-rpc-mcp-guide.html#python_compat">Python MCP Compatibility Notes</a></li>
</ul>
</li>