Google Git
Sign in
apache/axis-site/refs/heads/master/./axis2/java/core/docs/openapi-rest-advanced-userguide.html
blob: f69974901c673155ca639aca3280f45f67e8f51b [file]
<!DOCTYPE html>
<!--
| Generated by Apache Maven Doxia Site Renderer 2.0.0 from src/site/xdoc/docs/openapi-rest-advanced-userguide.xml at 2026-05-18
| Rendered using Apache Maven Fluido Skin 2.0.0-M11
-->
<html xmlns="http://www.w3.org/1999/xhtml" lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<meta name="generator" content="Apache Maven Doxia Site Renderer 2.0.0" />
<title>Apache Axis2 OpenAPI Advanced Enterprise User Guide – Apache Axis2</title>
<link rel="stylesheet" href="../css/apache-maven-fluido-2.0.0-M11.min.css" />
<link rel="stylesheet" href="../css/site.css" />
<link rel="stylesheet" href="../css/print.css" media="print" />
<script src="../js/apache-maven-fluido-2.0.0-M11.min.js"></script>
<meta http-equiv="content-type" content="" /> </head>
<body>
<div class="container-fluid container-fluid-top">
<header>
<div id="banner">
<div class="pull-left"><div id="bannerLeft"><h1><a href="https://www.apache.org/"><img class="class java.lang.Object" src="https://www.apache.org/images/asf_logo_wide.png" /> Apache Axis2</a></h1></div></div>
<div class="pull-right"><div id="bannerRight"><h1><a href="https://axis.apache.org/axis2/java/core/"><img class="class java.lang.Object" src="https://axis.apache.org/axis2/java/core/images/axis.jpg" /></a></h1></div></div>
<div class="clear"><hr/></div>
</div>
<div id="breadcrumbs">
<ul class="breadcrumb">
<li id="publishDate">Last Published: 2026-05-17<span class="divider">|</span>
</li>
<li id="projectVersion">Version: 2.0.1<span class="divider">|</span></li>
<li><a href="https://www.apache.org" class="externalLink">Apache</a><span class="divider">/</span></li>
<li><a href="../index.html">Axis2/Java</a><span class="divider">/</span></li>
<li class="active">Apache Axis2 OpenAPI Advanced Enterprise User Guide</li>
</ul>
</div>
</header>
<div class="row-fluid">
<header id="leftColumn" class="span2">
<nav class="well sidebar-nav">
<ul class="nav nav-list">
<li class="nav-header">Axis2/Java</li>
<li><a href="../index.html">Home</a></li>
<li><a href="../download.html">Downloads</a></li>
<li><a href="javascript:void(0)"><span class="icon-chevron-down"></span>Release Notes</a>
<ul class="nav nav-list">
<li><a href="../release-notes/1.6.1.html">1.6.1</a></li>
<li><a href="../release-notes/1.6.2.html">1.6.2</a></li>
<li><a href="../release-notes/1.6.3.html">1.6.3</a></li>
<li><a href="../release-notes/1.6.4.html">1.6.4</a></li>
<li><a href="../release-notes/1.7.0.html">1.7.0</a></li>
<li><a href="../release-notes/1.7.1.html">1.7.1</a></li>
<li><a href="../release-notes/1.7.2.html">1.7.2</a></li>
<li><a href="../release-notes/1.7.3.html">1.7.3</a></li>
<li><a href="../release-notes/1.7.4.html">1.7.4</a></li>
<li><a href="../release-notes/1.7.5.html">1.7.5</a></li>
<li><a href="../release-notes/1.7.6.html">1.7.6</a></li>
<li><a href="../release-notes/1.7.7.html">1.7.7</a></li>
<li><a href="../release-notes/1.7.8.html">1.7.8</a></li>
<li><a href="../release-notes/1.7.9.html">1.7.9</a></li>
<li><a href="../release-notes/1.8.0.html">1.8.0</a></li>
<li><a href="../release-notes/1.8.1.html">1.8.1</a></li>
<li><a href="../release-notes/1.8.2.html">1.8.2</a></li>
<li><a href="../release-notes/2.0.0.html">2.0.0</a></li>
<li><a href="../release-notes/2.0.1.html">2.0.1</a></li>
</ul></li>
<li><a href="../modules/index.html">Modules</a></li>
<li><a href="../tools/index.html">Tools</a></li>
<li class="nav-header">Documentation</li>
<li><a href="../docs/toc.html">Table of Contents</a></li>
<li><a href="../docs/installationguide.html">Installation Guide</a></li>
<li><a href="../docs/quickstartguide.html">QuickStart Guide</a></li>
<li><a href="../docs/userguide.html">User Guide</a></li>
<li><a href="../docs/jaxws-guide.html">JAXWS Guide</a></li>
<li><a href="../docs/pojoguide.html">POJO Guide</a></li>
<li><a href="../docs/spring.html">Spring Guide</a></li>
<li><a href="../docs/webadminguide.html">Web Administrator&apos;s Guide</a></li>
<li><a href="../docs/migration.html">Migration Guide (from Axis1)</a></li>
<li class="nav-header">Resources</li>
<li><a href="../faq.html">FAQ</a></li>
<li><a href="https://github.com/apache/axis-axis2-java-core" class="externalLink">Source Code</a></li>
<li class="nav-header">Get Involved</li>
<li><a href="../overview.html">Overview</a></li>
<li><a href="../mail-lists.html">Mailing Lists</a></li>
<li><a href="../release-process.html">Release Process</a></li>
<li><a href="../guidelines.html">Developer Guidelines</a></li>
<li><a href="../siteHowTo.html">Build the Site</a></li>
<li class="nav-header">Project Information</li>
<li><a href="https://github.com/apache/axis-axis2-java-core/graphs/contributors" class="externalLink">Contributors</a></li>
<li><a href="https://issues.apache.org/jira/projects/AXIS2/issues" class="externalLink">Issues</a></li>
<li class="nav-header">Apache</li>
<li><a href="https://www.apache.org/licenses/LICENSE-2.0.html" class="externalLink">License</a></li>
<li><a href="https://www.apache.org/foundation/sponsorship.html" class="externalLink">Sponsorship</a></li>
<li><a href="https://www.apache.org/foundation/thanks.html" class="externalLink">Thanks</a></li>
<li><a href="https://www.apache.org/security/" class="externalLink">Security</a></li>
</ul>
</nav>
<div class="well sidebar-nav">
<div id="poweredBy">
<div class="clear"></div>
<div class="clear"></div>
<a href="https://maven.apache.org/" class="builtBy" target="_blank"><img class="builtBy" alt="Built by Maven" src="../images/logos/maven-feather.png" /></a>
</div>
</div>
</header>
<main id="bodyColumn" class="span10">
<html>
<a id="_Toc96697850"></a>
<section><a id="Apache_Axis2_OpenAPI_Advanced_Enterprise_User_Guide"></a>
<h1>Apache Axis2 OpenAPI Advanced Enterprise User Guide</h1>
<p><strong>Enterprise-Grade OpenAPI Integration</strong> - This advanced guide demonstrates the comprehensive
OpenAPI capabilities introduced in Axis2 2.0.1, featuring enterprise-ready configuration management,
modern authentication patterns including Bearer tokens and OAuth2, advanced security schemes, and
sophisticated customization options. Perfect for building modern REST APIs that meet enterprise
requirements for security, scalability, and developer experience.</p>
<p><strong>New in Axis2 2.0.1:</strong> Complete enterprise-grade OpenAPI system with 40+ configuration
options, multi-source configuration loading (properties files, system properties, environment variables),
comprehensive security scheme integration (OAuth2, API Key, Bearer, Basic Auth), advanced SwaggerUI
customization with 20+ options, OpenAPI customizer interface for post-processing, intelligent resource
filtering, and performance optimizations.</p>
<p>This guide focuses on modern enterprise patterns including Bearer token authentication, OAuth2
integration, microservices architectures, cloud-native deployments, and developer-first API design
principles. All examples use contemporary security and architectural patterns.</p>
<p>For legacy system integration patterns, see the <a href="openapi-rest-userguide.html">Basic OpenAPI User Guide</a>.</p>
<a id="Introduction"></a>
<section><a id="Introduction_-_Enterprise_OpenAPI_Architecture"></a>
<h2>Introduction - Enterprise OpenAPI Architecture</h2>
<p>Axis2's OpenAPI integration represents a complete enterprise-grade solution for REST API development,
documentation, and management. Unlike basic API documentation tools, this system provides:</p>
<ul>
<li><strong>Configuration-Driven Architecture:</strong> 40+ configurable properties with multi-source loading</li>
<li><strong>Enterprise Security:</strong> OAuth2, JWT Bearer tokens, API keys, and custom authentication schemes</li>
<li><strong>Developer Experience:</strong> Advanced SwaggerUI with 20+ customization options</li>
<li><strong>Extensibility:</strong> OpenAPI customizer interface for post-processing and enhancements</li>
<li><strong>Performance:</strong> Intelligent caching, resource filtering, and optimization</li>
<li><strong>Cloud-Native:</strong> Environment variable support, container-ready configuration</li>
</ul>
<p>This guide assumes familiarity with modern REST API design, OAuth2/JWT authentication, and
enterprise development patterns. All examples follow contemporary security and architectural practices.</p>
</section><section><a id="Enterprise_Configuration_System"></a>
<h2>Enterprise Configuration System</h2>
<p>The Axis2 OpenAPI module provides a sophisticated configuration system supporting multiple
sources and precedence levels, designed for enterprise deployment scenarios.</p>
<section><a id="Configuration_Sources_and_Precedence"></a>
<h3>Configuration Sources and Precedence</h3>
<p>Configuration is loaded from multiple sources in the following precedence order (highest to lowest):</p>
<ol style="list-style-type: decimal;">
<li><strong>System Properties</strong> - JVM system properties (highest precedence)</li>
<li><strong>Environment Variables</strong> - OS environment variables</li>
<li><strong>Properties Files</strong> - Classpath properties files</li>
<li><strong>Module Parameters</strong> - axis2.xml module configuration</li>
<li><strong>Default Values</strong> - Built-in defaults (lowest precedence)</li>
</ol>
</section><section><a id="Properties_File_Configuration"></a>
<h3>Properties File Configuration</h3>
<p>Create <code>openapi.properties</code> in your classpath for comprehensive configuration:</p>
<pre>
# API Information
openapi.title=Financial Services API
openapi.description=Enterprise financial services with comprehensive security
openapi.version=2.1.0
openapi.contact.name=API Team
openapi.contact.email=api-team@company.com
openapi.contact.url=https://company.com/api-docs
openapi.license.name=Commercial License
openapi.license.url=https://company.com/license
openapi.termsOfServiceUrl=https://company.com/terms
# Security Configuration
openapi.security.oauth2.enabled=true
openapi.security.oauth2.authorizationUrl=https://auth.company.com/oauth2/authorize
openapi.security.oauth2.tokenUrl=https://auth.company.com/oauth2/token
openapi.security.oauth2.scopes=read:markets,write:trades,admin:users
openapi.security.apikey.enabled=true
openapi.security.apikey.name=X-API-Key
openapi.security.apikey.location=header
# Resource Filtering
openapi.readAllResources=false
openapi.resourcePackages=com.company.api.v2,com.company.services
openapi.resourceClasses=com.company.api.AuthController,com.company.api.TradeController
openapi.ignoredRoutes=/internal/.*,/health,/metrics
# Swagger UI Configuration
openapi.swaggerUi.enabled=true
openapi.swaggerUi.version=4.18.0
openapi.swaggerUi.deepLinking=true
openapi.swaggerUi.docExpansion=none
openapi.swaggerUi.filter=true
openapi.swaggerUi.customCss=/assets/custom-swagger.css
openapi.swaggerUi.customJs=/assets/custom-swagger.js
# Performance and Behavior
openapi.prettyPrint=false
openapi.useContextBasedConfig=true
openapi.scanKnownConfigLocations=true
</pre>
</section><section><a id="Environment_Variable_Configuration"></a>
<h3>Environment Variable Configuration</h3>
<p>All properties can be overridden with environment variables for cloud deployments:</p>
<pre>
# Docker/Kubernetes environment variables
OPENAPI_TITLE=&quot;Production Financial API&quot;
OPENAPI_SECURITY_OAUTH2_ENABLED=true
OPENAPI_SECURITY_OAUTH2_TOKEN_URL=https://prod-auth.company.com/oauth2/token
OPENAPI_SWAGGER_UI_ENABLED=false # Disable UI in production
OPENAPI_RESOURCE_PACKAGES=com.company.api.prod
</pre>
</section><section><a id="System_Properties_Configuration"></a>
<h3>System Properties Configuration</h3>
<p>Override any setting with JVM system properties:</p>
<pre>
java -Dopenapi.title=&quot;Development API&quot; \
-Dopenapi.security.oauth2.enabled=false \
-Dopenapi.swaggerUi.enabled=true \
-jar your-application.jar
</pre>
</section></section><section><a id="Modern_Authentication_Patterns"></a>
<h2>Modern Authentication Patterns</h2>
<p>The OpenAPI system supports modern authentication patterns including OAuth2, JWT Bearer tokens,
and API keys with comprehensive security scheme integration.</p>
<section><a id="Bearer_Token_Authentication_.28JWT.29"></a>
<h3>Bearer Token Authentication (JWT)</h3>
<p>Modern REST APIs use Bearer token authentication. Configure JWT Bearer tokens:</p>
<pre>
# properties configuration
openapi.security.bearer.enabled=true
openapi.security.bearer.format=JWT
openapi.security.bearer.description=JWT Bearer token authentication
</pre>
<p>Service implementation with Bearer authentication:</p>
<pre>
@Path(&quot;/api/v2&quot;)
@Tag(name = &quot;Financial Services API v2&quot;, description = &quot;Financial Services API v2&quot;)
public class FinancialServicesController {
@POST
@Path(&quot;/trades&quot;)
@Consumes(MediaType.APPLICATION_JSON)
@Produces(MediaType.APPLICATION_JSON)
@Operation(
summary = &quot;Create new trade&quot;,
description = &quot;Create a new trade with Bearer token authentication&quot;,
security = @SecurityRequirement(name = &quot;bearerAuth&quot;)
)
@ApiResponses({
@ApiResponse(responseCode = &quot;201&quot;, description = &quot;Trade created successfully&quot;),
@ApiResponse(responseCode = &quot;401&quot;, description = &quot;Unauthorized - invalid token&quot;),
@ApiResponse(responseCode = &quot;403&quot;, description = &quot;Forbidden - insufficient permissions&quot;)
})
public TradeResponse createTrade(
@HeaderParam(&quot;Authorization&quot;) String bearerToken,
@Parameter(description = &quot;Trade details&quot;) @Valid TradeRequest request) {
// Extract JWT token from Bearer header
String jwt = extractJwtFromBearerHeader(bearerToken);
// Validate JWT and extract user claims
JwtClaims claims = jwtValidator.validateToken(jwt);
UserContext userContext = UserContext.fromJwtClaims(claims);
// Business logic with authenticated user context
Trade trade = tradeService.createTrade(request, userContext);
return TradeResponse.from(trade);
}
private String extractJwtFromBearerHeader(String bearerToken) {
if (bearerToken == null || !bearerToken.startsWith(&quot;Bearer &quot;)) {
throw new UnauthorizedException(&quot;Invalid Bearer token format&quot;);
}
return bearerToken.substring(7);
}
}
</pre>
<p>Client usage with Bearer tokens:</p>
<pre>
# Login to get JWT token
curl -X POST https://api.company.com/auth/login \
-H &quot;Content-Type: application/json&quot; \
-d '{&quot;username&quot;:&quot;user@company.com&quot;,&quot;password&quot;:&quot;secure123&quot;}'
# Response:
{
&quot;access_token&quot;: &quot;eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...&quot;,
&quot;token_type&quot;: &quot;bearer&quot;,
&quot;expires_in&quot;: 3600,
&quot;scope&quot;: &quot;read:trades write:trades&quot;
}
# Use JWT token for API calls
curl -X POST https://api.company.com/api/v2/trades \
-H &quot;Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...&quot; \
-H &quot;Content-Type: application/json&quot; \
-d '{
&quot;symbol&quot;: &quot;AAPL&quot;,
&quot;quantity&quot;: 100,
&quot;side&quot;: &quot;BUY&quot;,
&quot;orderType&quot;: &quot;MARKET&quot;
}'
</pre>
</section><section><a id="OAuth2_Integration"></a>
<h3>OAuth2 Integration</h3>
<p>Complete OAuth2 flow configuration for enterprise security:</p>
<pre>
# OAuth2 configuration
openapi.security.oauth2.enabled=true
openapi.security.oauth2.authorizationUrl=https://auth.company.com/oauth2/authorize
openapi.security.oauth2.tokenUrl=https://auth.company.com/oauth2/token
openapi.security.oauth2.refreshUrl=https://auth.company.com/oauth2/refresh
openapi.security.oauth2.scopes=read:markets,write:trades,admin:users,read:reports
</pre>
<p>OAuth2 service implementation:</p>
<pre>
@Path(&quot;/api/v2/reports&quot;)
@Tag(name = &quot;Financial Reports API&quot;, description = &quot;Financial Reports API&quot;)
public class ReportsController {
@GET
@Path(&quot;/portfolio/{portfolioId}&quot;)
@Produces(MediaType.APPLICATION_JSON)
@Operation(
summary = &quot;Get portfolio report&quot;,
description = &quot;Requires 'read:reports' scope&quot;,
security = @SecurityRequirement(name = &quot;oauth2&quot;, scopes = {&quot;read:reports&quot;})
)
public PortfolioReport getPortfolioReport(
@HeaderParam(&quot;Authorization&quot;) String bearerToken,
@PathParam(&quot;portfolioId&quot;) @Parameter(description = &quot;Portfolio identifier&quot;) String portfolioId) {
// Validate OAuth2 token and scopes
OAuth2TokenInfo tokenInfo = oauth2Validator.validateToken(bearerToken);
if (!tokenInfo.hasScope(&quot;read:reports&quot;)) {
throw new ForbiddenException(&quot;Insufficient scope for reports access&quot;);
}
return reportsService.generatePortfolioReport(portfolioId, tokenInfo.getUserId());
}
}
</pre>
</section><section><a id="API_Key_Authentication"></a>
<h3>API Key Authentication</h3>
<p>Enterprise API key management with flexible header configuration:</p>
<pre>
# API Key configuration
openapi.security.apikey.enabled=true
openapi.security.apikey.name=X-API-Key
openapi.security.apikey.location=header
openapi.security.apikey.description=Enterprise API key for programmatic access
</pre>
<p>Service with API key authentication:</p>
<pre>
@Path(&quot;/api/v2/market-data&quot;)
@Tag(name = &quot;Market Data API&quot;, description = &quot;Market Data API&quot;)
public class MarketDataController {
@GET
@Path(&quot;/quotes/{symbol}&quot;)
@Produces(MediaType.APPLICATION_JSON)
@Operation(
summary = &quot;Get real-time quote&quot;,
description = &quot;Requires valid API key&quot;,
security = @SecurityRequirement(name = &quot;apiKeyAuth&quot;)
)
public QuoteResponse getQuote(
@HeaderParam(&quot;X-API-Key&quot;) @Parameter(description = &quot;API Key&quot;) String apiKey,
@PathParam(&quot;symbol&quot;) @Parameter(description = &quot;Stock symbol&quot;) String symbol) {
// Validate API key and get associated permissions
ApiKeyInfo keyInfo = apiKeyService.validateKey(apiKey);
if (!keyInfo.hasMarketDataAccess()) {
throw new ForbiddenException(&quot;API key does not have market data access&quot;);
}
Quote quote = marketDataService.getRealTimeQuote(symbol);
return QuoteResponse.from(quote);
}
}
</pre>
</section></section><section><a id="Advanced_Security_Scheme_Configuration"></a>
<h2>Advanced Security Scheme Configuration</h2>
<p>The OpenAPI system supports multiple simultaneous security schemes with sophisticated configuration options.</p>
<section><a id="Multi-Security_Scheme_Setup"></a>
<h3>Multi-Security Scheme Setup</h3>
<p>Configure multiple authentication methods for different API endpoints:</p>
<pre>
# Multiple security schemes configuration
openapi.security.bearer.enabled=true
openapi.security.bearer.format=JWT
openapi.security.bearer.description=JWT Bearer tokens for user authentication
openapi.security.apikey.enabled=true
openapi.security.apikey.name=X-API-Key
openapi.security.apikey.location=header
openapi.security.apikey.description=API keys for service-to-service communication
openapi.security.oauth2.enabled=true
openapi.security.oauth2.authorizationUrl=https://auth.company.com/oauth2/authorize
openapi.security.oauth2.tokenUrl=https://auth.company.com/oauth2/token
openapi.security.oauth2.scopes=read:data,write:data,admin:system
openapi.security.basic.enabled=false # Disable basic auth for security
</pre>
</section><section><a id="Programmatic_Security_Configuration"></a>
<h3>Programmatic Security Configuration</h3>
<p>Advanced security setup using the OpenApiCustomizer interface:</p>
<pre>
@Component
public class SecuritySchemeCustomizer implements OpenApiCustomizer {
@Override
public void customize(OpenAPI openAPI) {
// Add OAuth2 security scheme with detailed flow configuration
SecurityScheme oauth2 = new SecurityScheme()
.type(SecurityScheme.Type.OAUTH2)
.description(&quot;OAuth2 authentication with PKCE support&quot;)
.flows(new OAuthFlows()
.authorizationCode(new OAuthFlow()
.authorizationUrl(&quot;https://auth.company.com/oauth2/authorize&quot;)
.tokenUrl(&quot;https://auth.company.com/oauth2/token&quot;)
.refreshUrl(&quot;https://auth.company.com/oauth2/refresh&quot;)
.scopes(createOAuth2Scopes())
)
);
// Add JWT Bearer token scheme
SecurityScheme bearerAuth = new SecurityScheme()
.type(SecurityScheme.Type.HTTP)
.scheme(&quot;bearer&quot;)
.bearerFormat(&quot;JWT&quot;)
.description(&quot;JWT Bearer token authentication&quot;);
// Add enterprise API key scheme
SecurityScheme apiKeyAuth = new SecurityScheme()
.type(SecurityScheme.Type.APIKEY)
.name(&quot;X-API-Key&quot;)
.in(SecurityScheme.In.HEADER)
.description(&quot;Enterprise API key for service authentication&quot;);
// Register all security schemes
openAPI.getComponents()
.addSecuritySchemes(&quot;oauth2&quot;, oauth2)
.addSecuritySchemes(&quot;bearerAuth&quot;, bearerAuth)
.addSecuritySchemes(&quot;apiKeyAuth&quot;, apiKeyAuth);
// Add global security requirements
openAPI.addSecurityItem(new SecurityRequirement().addList(&quot;bearerAuth&quot;))
.addSecurityItem(new SecurityRequirement().addList(&quot;apiKeyAuth&quot;))
.addSecurityItem(new SecurityRequirement().addList(&quot;oauth2&quot;));
}
private Scopes createOAuth2Scopes() {
return new Scopes()
.addString(&quot;read:markets&quot;, &quot;Read access to market data&quot;)
.addString(&quot;write:trades&quot;, &quot;Execute trades and orders&quot;)
.addString(&quot;read:portfolio&quot;, &quot;Read portfolio information&quot;)
.addString(&quot;write:portfolio&quot;, &quot;Modify portfolio settings&quot;)
.addString(&quot;admin:users&quot;, &quot;Administrative access to user management&quot;)
.addString(&quot;admin:system&quot;, &quot;System administration privileges&quot;);
}
@Override
public int getPriority() {
return 100; // High priority for security configuration
}
}
</pre>
</section></section><section><a id="Advanced_SwaggerUI_Customization"></a>
<h2>Advanced SwaggerUI Customization</h2>
<p>The OpenAPI system provides extensive SwaggerUI customization capabilities for enterprise branding and functionality.</p>
<section><a id="Complete_SwaggerUI_Configuration"></a>
<h3>Complete SwaggerUI Configuration</h3>
<pre>
# Complete SwaggerUI customization
openapi.swaggerUi.enabled=true
openapi.swaggerUi.version=4.18.0
# UI Behavior Configuration
openapi.swaggerUi.deepLinking=true
openapi.swaggerUi.docExpansion=none
openapi.swaggerUi.filter=true
openapi.swaggerUi.displayOperationId=true
openapi.swaggerUi.displayRequestDuration=true
openapi.swaggerUi.defaultModelsExpandDepth=2
openapi.swaggerUi.defaultModelExpandDepth=2
openapi.swaggerUi.maxDisplayedTags=20
# Request/Response Configuration
openapi.swaggerUi.showRequestHeaders=true
openapi.swaggerUi.showResponseHeaders=true
openapi.swaggerUi.supportedSubmitMethods=get,post,put,delete,patch
openapi.swaggerUi.validatorUrl=https://validator.company.com/validator
# OAuth2 Configuration for SwaggerUI
openapi.swaggerUi.oauth2RedirectUrl=https://api.company.com/swagger-ui/oauth2-redirect.html
openapi.swaggerUi.oauth2ClientId=swagger-ui-client
openapi.swaggerUi.oauth2ClientSecret=swagger-ui-secret
openapi.swaggerUi.oauth2Realm=company-api
openapi.swaggerUi.oauth2AppName=Financial Services API
# Custom Styling
openapi.swaggerUi.customCss=/assets/corporate-swagger-theme.css
openapi.swaggerUi.customJs=/assets/swagger-enhancements.js
</pre>
</section><section><a id="Corporate_Branding_with_Custom_CSS"></a>
<h3>Corporate Branding with Custom CSS</h3>
<p>Create corporate-themed SwaggerUI with custom CSS (<code>/assets/corporate-swagger-theme.css</code>):</p>
<pre>
/* Corporate theme for SwaggerUI */
.swagger-ui .topbar {
background-color: #1e3a8a;
border-bottom: 3px solid #3b82f6;
}
.swagger-ui .topbar .download-url-wrapper .select-label {
color: #ffffff;
}
.swagger-ui .info .title {
color: #1e3a8a;
font-size: 2.5em;
font-weight: 600;
}
.swagger-ui .info .description {
font-size: 1.1em;
line-height: 1.6;
color: #4b5563;
}
/* Corporate header styling */
.corporate-header {
background: linear-gradient(135deg, #1e3a8a 0%, #3b82f6 100%);
color: white;
padding: 20px;
margin-bottom: 20px;
border-radius: 8px;
}
.corporate-header h1 {
margin: 0;
font-size: 2em;
font-weight: 600;
}
.corporate-header p {
margin: 10px 0 0 0;
opacity: 0.9;
font-size: 1.1em;
}
/* Enhanced operation styling */
.swagger-ui .opblock.opblock-post {
border-color: #059669;
background: rgba(5, 150, 105, 0.1);
}
.swagger-ui .opblock.opblock-get {
border-color: #0284c7;
background: rgba(2, 132, 199, 0.1);
}
.swagger-ui .opblock.opblock-put {
border-color: #ea580c;
background: rgba(234, 88, 12, 0.1);
}
.swagger-ui .opblock.opblock-delete {
border-color: #dc2626;
background: rgba(220, 38, 38, 0.1);
}
/* Security badge styling */
.swagger-ui .auth-wrapper .authorize {
background: #059669;
border-color: #059669;
}
.swagger-ui .auth-wrapper .authorize:hover {
background: #047857;
border-color: #047857;
}
/* Enhanced model styling */
.swagger-ui .model-box {
background: #f8fafc;
border: 1px solid #e2e8f0;
border-radius: 6px;
}
.swagger-ui .model .model-title {
color: #1e3a8a;
font-weight: 600;
}
</pre>
</section><section><a id="Custom_JavaScript_Enhancements"></a>
<h3>Custom JavaScript Enhancements</h3>
<p>Add advanced functionality with custom JavaScript (<code>/assets/swagger-enhancements.js</code>):</p>
<pre>
// Corporate SwaggerUI enhancements
window.addEventListener('load', function() {
// Add corporate header
const infoSection = document.querySelector('.swagger-ui .info');
if (infoSection) {
const corporateHeader = document.createElement('div');
corporateHeader.className = 'corporate-header';
corporateHeader.innerHTML = `
</section></section></section><section><a id="Financial_Services_API"></a>
<h1>Financial Services API</h1>
<p>Enterprise-grade financial services with comprehensive security and monitoring</p>
<div class="api-status">
<span class="status-badge status-healthy">Production Ready</span>
<span class="version-badge">v2.1.0</span>
</div>
`;
infoSection.parentNode.insertBefore(corporateHeader, infoSection);
}
// Add authentication helper
const authorizeButton = document.querySelector('.btn.authorize');
if (authorizeButton) {
authorizeButton.addEventListener('click', function() {
console.log('Authentication dialog opened');
// Add custom authentication logic here
});
}
// Enhanced error handling
const originalFetch = window.fetch;
window.fetch = function(...args) {
return originalFetch.apply(this, args)
.then(response =&gt; {
if (response.status === 401) {
showAuthenticationError();
} else if (response.status &gt;= 500) {
showServerError();
}
return response;
})
.catch(error =&gt; {
showNetworkError(error);
throw error;
});
};
// Add helpful tooltips
addCustomTooltips();
// Initialize performance monitoring
initializePerformanceMonitoring();
});
function showAuthenticationError() {
const notification = document.createElement('div');
notification.className = 'auth-error-notification';
notification.innerHTML = `
<div class="notification-content">
<strong>Authentication Required</strong>
<p>Please authenticate using the Authorize button above</p>
</div>
`;
document.body.appendChild(notification);
setTimeout(() =&gt; notification.remove(), 5000);
}
function showServerError() {
console.warn('Server error detected - check API status');
}
function showNetworkError(error) {
console.error('Network error:', error);
}
function addCustomTooltips() {
// Add tooltips to enhance user experience
const operations = document.querySelectorAll('.opblock');
operations.forEach(op =&gt; {
const method = op.querySelector('.opblock-summary-method');
if (method) {
method.title = 'Click to expand operation details';
}
});
}
function initializePerformanceMonitoring() {
// Monitor API response times
const observer = new PerformanceObserver((list) =&gt; {
list.getEntries().forEach((entry) =&gt; {
if (entry.name.includes('/api/')) {
console.log(`API Call: ${entry.name} - ${entry.duration.toFixed(2)}ms`);
}
});
});
observer.observe({entryTypes: ['navigation', 'resource']});
}
</pre>
<section><a id="OpenAPI_Customizer_Interface"></a>
<h2>OpenAPI Customizer Interface</h2>
<p>The OpenApiCustomizer interface provides powerful post-processing capabilities for advanced OpenAPI specification enhancement.</p>
<section><a id="Advanced_Customizer_Implementation"></a>
<h3>Advanced Customizer Implementation</h3>
<pre>
@Component
@Order(100) // High priority
public class EnterpriseOpenApiCustomizer implements OpenApiCustomizer {
private final ApiDocumentationService documentationService;
private final SecurityConfigurationService securityService;
@Override
public void customize(OpenAPI openAPI) {
// Enhanced API information
enhanceApiInformation(openAPI);
// Add enterprise security schemes
configureEnterpriseSecuritySchemes(openAPI);
// Add custom extensions
addCustomExtensions(openAPI);
// Configure advanced servers
configureServers(openAPI);
// Add comprehensive examples
addComprehensiveExamples(openAPI);
// Configure enterprise tags
configureEnterpriseTags(openAPI);
}
private void enhanceApiInformation(OpenAPI openAPI) {
Info info = openAPI.getInfo();
// Add comprehensive contact information
info.contact(new Contact()
.name(&quot;API Development Team&quot;)
.email(&quot;api-team@company.com&quot;)
.url(&quot;https://company.com/api-support&quot;)
.extensions(Map.of(&quot;x-team-slack&quot;, &quot;#api-support&quot;))
);
// Add detailed license information
info.license(new License()
.name(&quot;Commercial License&quot;)
.url(&quot;https://company.com/api-license&quot;)
.extensions(Map.of(
&quot;x-license-type&quot;, &quot;commercial&quot;,
&quot;x-support-level&quot;, &quot;enterprise&quot;
))
);
// Add enterprise extensions
info.addExtension(&quot;x-api-category&quot;, &quot;financial-services&quot;);
info.addExtension(&quot;x-compliance&quot;, Arrays.asList(&quot;SOC2&quot;, &quot;PCI-DSS&quot;, &quot;ISO27001&quot;));
info.addExtension(&quot;x-rate-limits&quot;, Map.of(
&quot;requests-per-minute&quot;, 1000,
&quot;burst-requests&quot;, 100
));
}
private void configureEnterpriseSecuritySchemes(OpenAPI openAPI) {
Components components = openAPI.getComponents();
// OAuth2 with multiple flows
SecurityScheme oauth2 = new SecurityScheme()
.type(SecurityScheme.Type.OAUTH2)
.description(&quot;OAuth2 with PKCE support&quot;)
.flows(new OAuthFlows()
.authorizationCode(createAuthorizationCodeFlow())
.clientCredentials(createClientCredentialsFlow())
);
// JWT Bearer with detailed configuration
SecurityScheme jwtBearer = new SecurityScheme()
.type(SecurityScheme.Type.HTTP)
.scheme(&quot;bearer&quot;)
.bearerFormat(&quot;JWT&quot;)
.description(&quot;JWT Bearer tokens with RS256 signing&quot;)
.addExtension(&quot;x-token-issuer&quot;, &quot;https://auth.company.com&quot;)
.addExtension(&quot;x-token-audience&quot;, &quot;financial-api&quot;)
.addExtension(&quot;x-token-expiry&quot;, &quot;1h&quot;);
// Enterprise API key
SecurityScheme enterpriseApiKey = new SecurityScheme()
.type(SecurityScheme.Type.APIKEY)
.name(&quot;X-API-Key&quot;)
.in(SecurityScheme.In.HEADER)
.description(&quot;Enterprise API key with role-based permissions&quot;)
.addExtension(&quot;x-key-rotation&quot;, &quot;monthly&quot;)
.addExtension(&quot;x-permissions-model&quot;, &quot;rbac&quot;);
components.addSecuritySchemes(&quot;oauth2&quot;, oauth2)
.addSecuritySchemes(&quot;jwtBearer&quot;, jwtBearer)
.addSecuritySchemes(&quot;enterpriseApiKey&quot;, enterpriseApiKey);
}
private OAuthFlow createAuthorizationCodeFlow() {
return new OAuthFlow()
.authorizationUrl(&quot;https://auth.company.com/oauth2/authorize&quot;)
.tokenUrl(&quot;https://auth.company.com/oauth2/token&quot;)
.refreshUrl(&quot;https://auth.company.com/oauth2/refresh&quot;)
.scopes(createDetailedScopes())
.addExtension(&quot;x-pkce-required&quot;, true)
.addExtension(&quot;x-token-lifetime&quot;, &quot;1h&quot;)
.addExtension(&quot;x-refresh-token-lifetime&quot;, &quot;30d&quot;);
}
private OAuthFlow createClientCredentialsFlow() {
return new OAuthFlow()
.tokenUrl(&quot;https://auth.company.com/oauth2/token&quot;)
.scopes(createServiceScopes())
.addExtension(&quot;x-client-authentication&quot;, &quot;client_secret_jwt&quot;)
.addExtension(&quot;x-token-lifetime&quot;, &quot;1h&quot;);
}
private Scopes createDetailedScopes() {
return new Scopes()
.addString(&quot;read:profile&quot;, &quot;Read user profile information&quot;)
.addString(&quot;read:accounts&quot;, &quot;Read account information and balances&quot;)
.addString(&quot;read:transactions&quot;, &quot;Read transaction history&quot;)
.addString(&quot;write:trades&quot;, &quot;Execute trades and manage orders&quot;)
.addString(&quot;read:market-data&quot;, &quot;Access real-time market data&quot;)
.addString(&quot;write:portfolio&quot;, &quot;Modify portfolio allocations&quot;)
.addString(&quot;admin:users&quot;, &quot;Manage user accounts and permissions&quot;)
.addString(&quot;admin:system&quot;, &quot;System administration privileges&quot;);
}
private void addCustomExtensions(OpenAPI openAPI) {
// Add enterprise-specific extensions
openAPI.addExtension(&quot;x-api-governance&quot;, Map.of(
&quot;owner&quot;, &quot;financial-services-team&quot;,
&quot;lifecycle-stage&quot;, &quot;production&quot;,
&quot;sla-tier&quot;, &quot;gold&quot;
));
openAPI.addExtension(&quot;x-monitoring&quot;, Map.of(
&quot;health-check&quot;, &quot;/health&quot;,
&quot;metrics&quot;, &quot;/metrics&quot;,
&quot;traces&quot;, &quot;distributed-tracing-enabled&quot;
));
openAPI.addExtension(&quot;x-documentation&quot;, Map.of(
&quot;guides&quot;, &quot;https://docs.company.com/api/guides&quot;,
&quot;tutorials&quot;, &quot;https://docs.company.com/api/tutorials&quot;,
&quot;changelog&quot;, &quot;https://docs.company.com/api/changelog&quot;
));
}
private void configureServers(OpenAPI openAPI) {
openAPI.servers(Arrays.asList(
new Server()
.url(&quot;https://api.company.com&quot;)
.description(&quot;Production environment&quot;)
.addExtension(&quot;x-environment&quot;, &quot;production&quot;)
.addExtension(&quot;x-region&quot;, &quot;us-east-1&quot;),
new Server()
.url(&quot;https://staging-api.company.com&quot;)
.description(&quot;Staging environment&quot;)
.addExtension(&quot;x-environment&quot;, &quot;staging&quot;)
.addExtension(&quot;x-region&quot;, &quot;us-east-1&quot;),
new Server()
.url(&quot;https://dev-api.company.com&quot;)
.description(&quot;Development environment&quot;)
.addExtension(&quot;x-environment&quot;, &quot;development&quot;)
.addExtension(&quot;x-region&quot;, &quot;us-west-2&quot;)
));
}
@Override
public int getPriority() {
return 100;
}
@Override
public boolean shouldApply(OpenAPI openAPI) {
// Only apply to production and staging environments
String environment = System.getProperty(&quot;deployment.environment&quot;, &quot;development&quot;);
return Arrays.asList(&quot;production&quot;, &quot;staging&quot;).contains(environment);
}
}
</pre>
</section></section><section><a id="Resource_Management_and_Filtering"></a>
<h2>Resource Management and Filtering</h2>
<p>Advanced resource filtering and management capabilities for large-scale enterprise APIs.</p>
<section><a id="Intelligent_Resource_Discovery"></a>
<h3>Intelligent Resource Discovery</h3>
<pre>
# Resource filtering configuration
openapi.readAllResources=false
# Package-based filtering
openapi.resourcePackages=com.company.api.v2,com.company.services.financial,com.company.auth
# Class-based filtering
openapi.resourceClasses=com.company.api.TradesController,com.company.api.PortfolioController
# Route exclusion patterns
openapi.ignoredRoutes=/internal/.*,/admin/.*,/health,/metrics,/actuator/.*
# Custom resource scanner
openapi.scannerClass=com.company.config.CustomResourceScanner
</pre>
</section><section><a id="Custom_Resource_Scanner"></a>
<h3>Custom Resource Scanner</h3>
<pre>
@Component
public class CustomResourceScanner implements ResourceScanner {
@Override
public Set&lt;Class&lt;?&gt;&gt; scanForResources() {
Set&lt;Class&lt;?&gt;&gt; resources = new HashSet&lt;&gt;();
// Scan for annotated controllers
resources.addAll(scanForAnnotatedControllers());
// Scan for service interfaces
resources.addAll(scanForServiceInterfaces());
// Apply business rules for inclusion
return resources.stream()
.filter(this::shouldIncludeResource)
.collect(Collectors.toSet());
}
private Set&lt;Class&lt;?&gt;&gt; scanForAnnotatedControllers() {
// Custom logic for finding REST controllers
return ClasspathScanner.scan(&quot;com.company.api&quot;)
.filter(clazz -&gt; clazz.isAnnotationPresent(Path.class))
.filter(clazz -&gt; clazz.isAnnotationPresent(Tag.class))
.collect(Collectors.toSet());
}
private boolean shouldIncludeResource(Class&lt;?&gt; resource) {
// Business logic for resource inclusion
if (resource.isAnnotationPresent(InternalApi.class)) {
return false; // Exclude internal APIs
}
if (resource.isAnnotationPresent(DeprecatedApi.class)) {
DeprecatedApi deprecation = resource.getAnnotation(DeprecatedApi.class);
return !deprecation.excludeFromDocs(); // Include unless explicitly excluded
}
// Include by default
return true;
}
}
</pre>
</section></section><section><a id="Enterprise_Integration_Examples"></a>
<h2>Enterprise Integration Examples</h2>
<p>Complete examples demonstrating modern enterprise patterns with comprehensive security and functionality.</p>
<section><a id="Financial_Trading_API_with_Bearer_Authentication"></a>
<h3>Financial Trading API with Bearer Authentication</h3>
<pre>
@Path(&quot;/api/v2/trading&quot;)
@Tag(name = &quot;Trading API&quot;, description = &quot;Enterprise trading services with comprehensive security&quot;)
@Component
public class TradingController {
@Autowired
private TradingService tradingService;
@Autowired
private JwtTokenValidator tokenValidator;
@POST
@Path(&quot;/orders&quot;)
@Consumes(MediaType.APPLICATION_JSON)
@Produces(MediaType.APPLICATION_JSON)
@Operation(
summary = &quot;Place trading order&quot;,
description = &quot;Execute trading order with comprehensive validation and risk checks&quot;,
security = @SecurityRequirement(name = &quot;jwtBearer&quot;)
)
@ApiResponses({
@ApiResponse(responseCode = &quot;201&quot;, description = &quot;Order placed successfully&quot;,
content = @Content(schema = @Schema(implementation = OrderResponse.class))),
@ApiResponse(responseCode = &quot;400&quot;, description = &quot;Invalid order parameters&quot;,
content = @Content(schema = @Schema(implementation = ErrorResponse.class))),
@ApiResponse(responseCode = &quot;401&quot;, description = &quot;Authentication required&quot;,
content = @Content(schema = @Schema(implementation = ErrorResponse.class))),
@ApiResponse(responseCode = &quot;403&quot;, description = &quot;Insufficient trading permissions&quot;,
content = @Content(schema = @Schema(implementation = ErrorResponse.class))),
@ApiResponse(responseCode = &quot;429&quot;, description = &quot;Rate limit exceeded&quot;,
content = @Content(schema = @Schema(implementation = ErrorResponse.class)))
})
public Response placeOrder(
@HeaderParam(&quot;Authorization&quot;) @Parameter(description = &quot;Bearer JWT token&quot;) String bearerToken,
@Parameter(description = &quot;Order details&quot;) @Valid OrderRequest orderRequest,
@Context HttpServletRequest request) {
try {
// Extract and validate JWT token
String jwt = extractJwtToken(bearerToken);
JwtClaims claims = tokenValidator.validateToken(jwt);
// Create user context with permissions
UserContext userContext = UserContext.builder()
.userId(claims.getSubject())
.email(claims.getStringClaim(&quot;email&quot;))
.permissions(extractPermissions(claims))
.sessionId(claims.getJwtId())
.build();
// Validate trading permissions
validateTradingPermissions(userContext, orderRequest);
// Execute order with risk management
OrderResult result = tradingService.placeOrder(orderRequest, userContext);
// Build comprehensive response
OrderResponse response = OrderResponse.builder()
.orderId(result.getOrderId())
.status(result.getStatus())
.executionPrice(result.getExecutionPrice())
.executionTime(result.getExecutionTime())
.commission(result.getCommission())
.estimatedSettlement(result.getEstimatedSettlement())
.riskMetrics(result.getRiskMetrics())
.build();
return Response
.status(Response.Status.CREATED)
.entity(response)
.header(&quot;X-Order-Id&quot;, result.getOrderId())
.header(&quot;X-Request-Id&quot;, generateRequestId())
.build();
} catch (InvalidTokenException e) {
return createErrorResponse(Response.Status.UNAUTHORIZED, &quot;INVALID_TOKEN&quot;, e.getMessage());
} catch (InsufficientPermissionsException e) {
return createErrorResponse(Response.Status.FORBIDDEN, &quot;INSUFFICIENT_PERMISSIONS&quot;, e.getMessage());
} catch (OrderValidationException e) {
return createErrorResponse(Response.Status.BAD_REQUEST, &quot;INVALID_ORDER&quot;, e.getMessage());
} catch (RiskLimitExceededException e) {
return createErrorResponse(Response.Status.BAD_REQUEST, &quot;RISK_LIMIT_EXCEEDED&quot;, e.getMessage());
}
}
@GET
@Path(&quot;/orders/{orderId}&quot;)
@Produces(MediaType.APPLICATION_JSON)
@Operation(
summary = &quot;Get order status&quot;,
description = &quot;Retrieve detailed order information and execution status&quot;,
security = @SecurityRequirement(name = &quot;jwtBearer&quot;)
)
public Response getOrderStatus(
@HeaderParam(&quot;Authorization&quot;) String bearerToken,
@PathParam(&quot;orderId&quot;) @Parameter(description = &quot;Order identifier&quot;) String orderId) {
String jwt = extractJwtToken(bearerToken);
JwtClaims claims = tokenValidator.validateToken(jwt);
UserContext userContext = createUserContext(claims);
OrderStatus status = tradingService.getOrderStatus(orderId, userContext);
OrderStatusResponse response = OrderStatusResponse.from(status);
return Response.ok(response)
.header(&quot;Cache-Control&quot;, &quot;no-cache&quot;)
.header(&quot;X-Request-Id&quot;, generateRequestId())
.build();
}
private String extractJwtToken(String bearerToken) {
if (bearerToken == null || !bearerToken.startsWith(&quot;Bearer &quot;)) {
throw new InvalidTokenException(&quot;Invalid Bearer token format&quot;);
}
return bearerToken.substring(7);
}
private Set&lt;String&gt; extractPermissions(JwtClaims claims) {
try {
return new HashSet&lt;&gt;(claims.getStringListClaim(&quot;permissions&quot;));
} catch (Exception e) {
return Collections.emptySet();
}
}
private void validateTradingPermissions(UserContext userContext, OrderRequest orderRequest) {
if (!userContext.hasPermission(&quot;trade:execute&quot;)) {
throw new InsufficientPermissionsException(&quot;Trading permission required&quot;);
}
if (orderRequest.getOrderValue() &gt; 100000 &amp;&amp; !userContext.hasPermission(&quot;trade:large_orders&quot;)) {
throw new InsufficientPermissionsException(&quot;Large order permission required&quot;);
}
}
private Response createErrorResponse(Response.Status status, String errorCode, String message) {
ErrorResponse error = ErrorResponse.builder()
.errorCode(errorCode)
.message(message)
.timestamp(Instant.now())
.requestId(generateRequestId())
.build();
return Response.status(status)
.entity(error)
.header(&quot;X-Request-Id&quot;, error.getRequestId())
.build();
}
private String generateRequestId() {
return UUID.randomUUID().toString();
}
}
</pre>
</section><section><a id="Modern_Request.2FResponse_Models"></a>
<h3>Modern Request/Response Models</h3>
<pre>
@JsonInclude(JsonInclude.Include.NON_NULL)
@Schema(description = &quot;Trading order request with comprehensive validation&quot;)
public class OrderRequest {
@NotNull(message = &quot;Symbol is required&quot;)
@Pattern(regexp = &quot;[A-Z]{1,5}&quot;, message = &quot;Invalid symbol format&quot;)
@Schema(description = &quot;Stock symbol&quot;, required = true, example = &quot;AAPL&quot;)
private String symbol;
@NotNull(message = &quot;Order side is required&quot;)
@Schema(description = &quot;Order side&quot;, required = true, allowableValues = {&quot;BUY&quot;, &quot;SELL&quot;})
private OrderSide side;
@NotNull(message = &quot;Quantity is required&quot;)
@DecimalMin(value = &quot;0.01&quot;, message = &quot;Quantity must be positive&quot;)
@Schema(description = &quot;Order quantity&quot;, required = true, example = &quot;100&quot;)
private BigDecimal quantity;
@NotNull(message = &quot;Order type is required&quot;)
@Schema(description = &quot;Order type&quot;, required = true, allowableValues = {&quot;MARKET&quot;, &quot;LIMIT&quot;, &quot;STOP&quot;, &quot;STOP_LIMIT&quot;})
private OrderType orderType;
@Schema(description = &quot;Limit price (required for LIMIT and STOP_LIMIT orders)&quot;, example = &quot;150.50&quot;)
private BigDecimal limitPrice;
@Schema(description = &quot;Stop price (required for STOP and STOP_LIMIT orders)&quot;, example = &quot;145.00&quot;)
private BigDecimal stopPrice;
@NotNull(message = &quot;Time in force is required&quot;)
@Schema(description = &quot;Time in force&quot;, required = true, allowableValues = {&quot;DAY&quot;, &quot;GTC&quot;, &quot;IOC&quot;, &quot;FOK&quot;})
private TimeInForce timeInForce;
@Schema(description = &quot;Client order ID for tracking&quot;, example = &quot;CLIENT-ORDER-123&quot;)
private String clientOrderId;
@Valid
@Schema(description = &quot;Additional order parameters&quot;)
private OrderParameters parameters;
// Constructors, getters, setters, builder pattern
}
@JsonInclude(JsonInclude.Include.NON_NULL)
@Schema(description = &quot;Trading order response with execution details&quot;)
public class OrderResponse {
@Schema(description = &quot;Unique order identifier&quot;, example = &quot;ORD-12345678&quot;)
private String orderId;
@Schema(description = &quot;Current order status&quot;, allowableValues = {&quot;PENDING&quot;, &quot;FILLED&quot;, &quot;PARTIALLY_FILLED&quot;, &quot;CANCELLED&quot;, &quot;REJECTED&quot;})
private OrderStatus status;
@Schema(description = &quot;Order submission timestamp&quot;, example = &quot;2023-12-21T15:30:00Z&quot;)
private Instant submissionTime;
@Schema(description = &quot;Execution price (if filled)&quot;, example = &quot;150.25&quot;)
private BigDecimal executionPrice;
@Schema(description = &quot;Filled quantity&quot;, example = &quot;100&quot;)
private BigDecimal filledQuantity;
@Schema(description = &quot;Remaining quantity&quot;, example = &quot;0&quot;)
private BigDecimal remainingQuantity;
@Schema(description = &quot;Commission charged&quot;, example = &quot;0.99&quot;)
private BigDecimal commission;
@Schema(description = &quot;Estimated settlement date&quot;, example = &quot;2023-12-23&quot;)
private LocalDate estimatedSettlement;
@Valid
@Schema(description = &quot;Risk metrics for this order&quot;)
private RiskMetrics riskMetrics;
@Schema(description = &quot;Execution venue&quot;, example = &quot;NASDAQ&quot;)
private String venue;
// Constructors, getters, setters, builder pattern
}
@JsonInclude(JsonInclude.Include.NON_NULL)
@Schema(description = &quot;Risk metrics and compliance information&quot;)
public class RiskMetrics {
@Schema(description = &quot;Position delta after execution&quot;, example = &quot;0.15&quot;)
private BigDecimal positionDelta;
@Schema(description = &quot;Portfolio value at risk&quot;, example = &quot;25000.00&quot;)
private BigDecimal valueAtRisk;
@Schema(description = &quot;Regulatory compliance status&quot;)
private ComplianceStatus complianceStatus;
@Schema(description = &quot;Risk limit utilization percentage&quot;, example = &quot;45.5&quot;)
private BigDecimal riskUtilization;
// Additional risk metrics...
}
</pre>
</section></section><section><a id="Performance_and_Monitoring"></a>
<h2>Performance and Monitoring</h2>
<p>Enterprise-grade performance optimization and monitoring capabilities for production deployments.</p>
<section><a id="Performance_Configuration"></a>
<h3>Performance Configuration</h3>
<pre>
# Performance optimization settings
openapi.performance.caching.enabled=true
openapi.performance.caching.spec.ttl=300 # 5 minutes
openapi.performance.caching.ui.ttl=3600 # 1 hour
# Memory management
openapi.performance.streaming.enabled=true
openapi.performance.streaming.threshold=1048576 # 1MB
# Response compression
openapi.performance.compression.enabled=true
openapi.performance.compression.minSize=1024
# Connection pooling
openapi.performance.http.maxConnections=200
openapi.performance.http.connectionTimeout=5000
openapi.performance.http.readTimeout=30000
</pre>
</section><section><a id="Monitoring_and_Observability"></a>
<h3>Monitoring and Observability</h3>
<pre>
@Component
public class OpenApiMetricsCollector {
private final MeterRegistry meterRegistry;
private final Timer specGenerationTimer;
private final Counter apiCallCounter;
private final Gauge activeConnectionsGauge;
public OpenApiMetricsCollector(MeterRegistry meterRegistry) {
this.meterRegistry = meterRegistry;
this.specGenerationTimer = Timer.builder(&quot;openapi.spec.generation.time&quot;)
.description(&quot;Time taken to generate OpenAPI specification&quot;)
.register(meterRegistry);
this.apiCallCounter = Counter.builder(&quot;openapi.api.calls&quot;)
.description(&quot;Total API calls processed&quot;)
.register(meterRegistry);
this.activeConnectionsGauge = Gauge.builder(&quot;openapi.connections.active&quot;)
.description(&quot;Active connections to OpenAPI endpoints&quot;)
.register(meterRegistry, this, OpenApiMetricsCollector::getActiveConnections);
}
public void recordSpecGeneration(Duration duration) {
specGenerationTimer.record(duration);
}
public void recordApiCall(String endpoint, String method, int statusCode) {
apiCallCounter.increment(
Tags.of(
&quot;endpoint&quot;, endpoint,
&quot;method&quot;, method,
&quot;status&quot;, String.valueOf(statusCode)
)
);
}
private double getActiveConnections() {
// Implementation to get active connections
return 0.0;
}
}
@Component
public class OpenApiHealthIndicator implements HealthIndicator {
private final OpenApiSpecGenerator specGenerator;
private final SwaggerUIHandler uiHandler;
@Override
public Health health() {
try {
// Check OpenAPI spec generation
long startTime = System.currentTimeMillis();
specGenerator.generateOpenApiSpec(null);
long specGenTime = System.currentTimeMillis() - startTime;
// Check SwaggerUI availability
boolean uiAvailable = uiHandler.getConfiguration().isSupportSwaggerUi();
return Health.up()
.withDetail(&quot;specGenerationTime&quot;, specGenTime + &quot;ms&quot;)
.withDetail(&quot;swaggerUiEnabled&quot;, uiAvailable)
.withDetail(&quot;version&quot;, &quot;2.0.1&quot;)
.withDetail(&quot;configurationSource&quot;, getConfigurationSource())
.build();
} catch (Exception e) {
return Health.down()
.withDetail(&quot;error&quot;, e.getMessage())
.withException(e)
.build();
}
}
private String getConfigurationSource() {
// Determine primary configuration source
return &quot;properties-file&quot;;
}
}
</pre>
</section></section><section><a id="Cloud-Native_Deployment"></a>
<h2>Cloud-Native Deployment</h2>
<p>Configuration and deployment patterns for cloud-native and containerized environments.</p>
<section><a id="Docker_Configuration"></a>
<h3>Docker Configuration</h3>
<pre>
# Dockerfile
FROM openjdk:17-jre-slim
# Environment variables for OpenAPI configuration
ENV OPENAPI_TITLE=&quot;Financial Services API&quot;
ENV OPENAPI_SECURITY_OAUTH2_ENABLED=true
ENV OPENAPI_SWAGGER_UI_ENABLED=false
ENV OPENAPI_RESOURCE_PACKAGES=com.company.api.v2
# Copy application
COPY target/financial-api.war /opt/axis2/webapps/
COPY config/openapi-production.properties /opt/axis2/conf/
EXPOSE 8080
CMD [&quot;catalina.sh&quot;, &quot;run&quot;]
</pre>
</section><section><a id="Kubernetes_Configuration"></a>
<h3>Kubernetes Configuration</h3>
<pre>
apiVersion: v1
kind: ConfigMap
metadata:
name: openapi-config
data:
openapi.properties: |
openapi.title=Financial Services API
openapi.version=2.1.0
openapi.security.oauth2.enabled=true
openapi.security.oauth2.tokenUrl=https://auth.company.com/oauth2/token
openapi.swaggerUi.enabled=false
openapi.performance.caching.enabled=true
---
apiVersion: apps/v1
kind: Deployment
metadata:
name: financial-api
spec:
replicas: 3
selector:
matchLabels:
app: financial-api
template:
metadata:
labels:
app: financial-api
spec:
containers:
- name: api
image: company/financial-api:2.1.0
ports:
- containerPort: 8080
env:
- name: OPENAPI_TITLE
value: &quot;Production Financial API&quot;
- name: OPENAPI_SECURITY_OAUTH2_TOKEN_URL
valueFrom:
secretKeyRef:
name: oauth2-config
key: token-url
volumeMounts:
- name: openapi-config
mountPath: /opt/axis2/conf/openapi.properties
subPath: openapi.properties
livenessProbe:
httpGet:
path: /health
port: 8080
initialDelaySeconds: 30
periodSeconds: 10
readinessProbe:
httpGet:
path: /openapi.json
port: 8080
initialDelaySeconds: 5
periodSeconds: 5
volumes:
- name: openapi-config
configMap:
name: openapi-config
</pre>
</section></section><section><a id="Enterprise_Security_Best_Practices"></a>
<h2>Enterprise Security Best Practices</h2>
<p>Comprehensive security guidelines for production OpenAPI deployments.</p>
<section><a id="Production_Security_Checklist"></a>
<h3>Production Security Checklist</h3>
<ul>
<li><strong>&#x2713; JWT Token Validation:</strong> Implement proper JWT signature verification and expiration checking</li>
<li><strong>&#x2713; OAuth2 PKCE:</strong> Enforce PKCE for public clients and authorization code flows</li>
<li><strong>&#x2713; CORS Configuration:</strong> Restrict CORS origins to known domains in production</li>
<li><strong>&#x2713; Rate Limiting:</strong> Implement rate limiting per API key/user to prevent abuse</li>
<li><strong>&#x2713; Input Validation:</strong> Validate all request parameters against OpenAPI schemas</li>
<li><strong>&#x2713; HTTPS Only:</strong> Enforce HTTPS for all API endpoints and disable HTTP</li>
<li><strong>&#x2713; Security Headers:</strong> Include security headers (HSTS, CSP, X-Frame-Options)</li>
<li><strong>&#x2713; API Key Rotation:</strong> Implement regular API key rotation policies</li>
<li><strong>&#x2713; Audit Logging:</strong> Log all API access and authentication events</li>
<li><strong>&#x2713; SwaggerUI Security:</strong> Disable SwaggerUI in production or restrict access</li>
</ul>
</section><section><a id="Security_Configuration_Example"></a>
<h3>Security Configuration Example</h3>
<pre>
# Production security configuration
openapi.security.enforceHttps=true
openapi.security.hsts.enabled=true
openapi.security.hsts.maxAge=31536000
openapi.security.csp.enabled=true
openapi.security.csp.policy=default-src 'self'; script-src 'self' 'unsafe-inline'
# Disable SwaggerUI in production
openapi.swaggerUi.enabled=false
# Restrict CORS to known origins
openapi.cors.allowedOrigins=https://app.company.com,https://mobile.company.com
openapi.cors.allowCredentials=true
openapi.cors.maxAge=3600
# Rate limiting
openapi.rateLimiting.enabled=true
openapi.rateLimiting.requestsPerMinute=100
openapi.rateLimiting.burstLimit=20
# Audit logging
openapi.audit.enabled=true
openapi.audit.logFormat=JSON
openapi.audit.includeRequestBody=false
openapi.audit.includeResponseBody=false
</pre>
</section></section><section><a id="Troubleshooting_and_Advanced_Topics"></a>
<h2>Troubleshooting and Advanced Topics</h2>
<p>Common issues and advanced configuration scenarios for enterprise deployments.</p>
<section><a id="Common_Configuration_Issues"></a>
<h3>Common Configuration Issues</h3>
<ul>
<li><strong>Configuration Precedence:</strong> System properties override environment variables override properties files</li>
<li><strong>Security Scheme Validation:</strong> Ensure OAuth2 endpoints are accessible and properly configured</li>
<li><strong>Resource Filtering:</strong> Verify package names and class paths are correct</li>
<li><strong>Memory Usage:</strong> Monitor memory usage with large OpenAPI specifications</li>
<li><strong>Performance:</strong> Enable caching for frequently accessed specifications</li>
</ul>
</section><section><a id="Advanced_Debugging"></a>
<h3>Advanced Debugging</h3>
<pre>
# Enable debug logging
logging.level.org.apache.axis2.openapi=DEBUG
# JVM debugging options
-Dopenapi.debug=true
-Dopenapi.performance.monitoring=true
-Dopenapi.configuration.trace=true
</pre>
<p>For comprehensive support and advanced enterprise deployment scenarios, contact the Apache Axis2
development team or consult the <a href="openapi-rest-userguide.html">Basic OpenAPI User Guide</a>
for fundamental concepts.</p>
<p>This advanced guide demonstrates the full enterprise capabilities of Axis2's OpenAPI integration.
The system provides the flexibility and power needed for modern enterprise API development while
maintaining the reliability and performance expected in production environments.</p>
</section></section>
</html> </main>
</div>
</div>
<hr/>
<footer>
<div class="container-fluid">
<div class="row-fluid">
<p>© 2004–2026
<a href="https://www.apache.org/">The Apache Software Foundation</a>
</p>
</div>
</div>
</footer>
</body>
</html>