Key OpenAPI Features

• Multiple Generation Modes: AUTOMATIC (service introspection), STATIC (manual schemas), and HYBRID (base generation with static overrides)
• Interactive Documentation: Built-in Swagger UI at /swagger-ui endpoint for API testing and exploration
• Standard Endpoints: OpenAPI specifications served at /openapi.json and /openapi.yaml
• CORS Support: Enabled by default for browser-based testing and frontend integration
• Service Discovery: Automatic detection of REST-enabled Axis2 services
• Drop-in Compatibility: Designed to replace existing REST backends without frontend changes

OpenAPI Generation Modes

The OpenAPI module automatically selects the optimal documentation generation approach:

• AUTOMATIC Mode: Generate complete OpenAPI specs from Axis2 service metadata and annotations - ideal for new services
• STATIC Mode: Use manually crafted OpenAPI schema files for precise API contracts - perfect for existing API specifications
• HYBRID Mode: Combine automatic base generation with static schema enhancements - balances automation with customization for complex enterprise requirements

Drop-in Backend Replacement

The Axis2 OpenAPI integration is specifically designed for backend replacement scenarios:

• API Compatibility: Maintain existing endpoint paths, request/response formats
• Authentication Patterns: Support for custom headers and standard Bearer tokens
• Frontend Support: Compatible with TypeScript clients, Excel Add-ins, React apps
• Migration Path: Gradual service-by-service replacement without breaking changes

Sample Services Overview

The swagger-server sample provides three comprehensive services demonstrating different aspects of enterprise REST API development:

• AuthenticationService: Login/authentication with custom token generation
• DataManagementService: Market data processing and financial calculation services
• ExcelIntegrationService: Excel Add-in specific endpoints and metadata

Authentication Service

The AuthenticationService demonstrates token-based authentication using OpenAPI 3.x annotations (from io.swagger.v3.oas.annotations):

@Path("/api/auth")
@Tag(name = "authentication", description = "User authentication and token management")
public class AuthenticationService {

    @POST
    @Path("/login")
    @Consumes(MediaType.APPLICATION_JSON)
    @Produces(MediaType.APPLICATION_JSON)
    @Operation(summary = "User authentication",
               description = "Authenticate user and return access token")
    public LoginResponse login(LoginRequest request) {
        // Token generation and validation logic
    }
}

Data Service

A data service with authenticated endpoints:

@Path("/api/data")
@Tag(name = "data", description = "Data management operations")
public class DataService {

    @POST
    @Path("/query")
    @Operation(summary = "Query dataset",
               description = "Retrieve filtered data with pagination")
    public QueryResponse query(
            @Parameter(description = "Query parameters") QueryRequest request,
            @HeaderParam("Authorization") String bearerToken) {
        // Data processing logic
    }

    @POST
    @Path("/calculate")
    @Operation(summary = "Run calculation")
    public CalculationResponse calculate(
            CalculationRequest request,
            @HeaderParam("Authorization") String bearerToken) {
        // Calculation logic
    }
}

Note: Axis2's OpenAPI integration uses io.swagger.v3.oas.annotations (OpenAPI 3.x), not the older Swagger 1.x annotations (@Api, @ApiOperation, @ApiParam). See the Swagger 2.x annotation guide for the full reference.

Request/Response Models

Axis2 supports multiple JSON libraries — Moshi, Gson, and a streaming formatter — each with standard and HTTP/2-enhanced variants. Select the library by choosing the corresponding message builder and formatter classes in axis2.xml. The examples below use Moshi's @Json annotation; Gson provides equivalent functionality with @SerializedName:

public class LoginRequest {
    @Json(name = "email")
    private String email;

    @Json(name = "credentials")
    private String credentials;

    // Getters and setters
}

public class LoginResponse {
    @Json(name = "data")
    private LoginData data;

    @Json(name = "errorMessage")
    private String errorMessage;

    // Compatible with existing frontend expectations
}

OpenAPI Configuration Parameters

• generationMode: AUTOMATIC (introspection), STATIC (schema files), or HYBRID (combined)
• staticSchemaPath: Path to static OpenAPI schema file (for STATIC/HYBRID modes)
• enableSwaggerUI: Enable interactive Swagger UI (default: true)
• swaggerUIPath: Swagger UI endpoint path (default: /swagger-ui)
• enableCORS: Enable CORS headers for browser access (default: true)
• apiTitle: API title in OpenAPI spec (default: "Apache Axis2 REST API")
• apiVersion: API version (default: "1.0.0")

Static Schema Integration

For drop-in replacement scenarios, use STATIC or HYBRID mode with existing OpenAPI schemas:

<!-- STATIC mode: Use existing OpenAPI schema file -->
<parameter name="openapi.generationMode">STATIC</parameter>
<parameter name="openapi.staticSchemaPath">existing-api-schema.json</parameter>

<!-- HYBRID mode: Enhance introspection with static schema -->
<parameter name="openapi.generationMode">HYBRID</parameter>
<parameter name="openapi.staticSchemaPath">api-enhancements.json</parameter>

Authentication - Custom Token Pattern

Login request maintaining existing frontend patterns:

curl -v -H "Content-Type: application/json" \
     -X POST \
     --data '{"email":"user@company.com","credentials":"password123"}' \
     http://localhost:8080/axis2/services/authService/login

Response format compatible with existing frontends:

{
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "userId": "user123",
    "email": "user@company.com"
  },
  "errorMessage": null
}

Data Services - Custom Header Authentication

Data requests using custom bigdataToken header (maintaining frontend compatibility):

curl -v -H "bigdataToken: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
     -H "Content-Type: application/json" \
     -X POST \
     --data '{"marketId":"MKT001","includeHistory":true}' \
     http://localhost:8080/axis2/services/dataService/marketSummary

Where the response maintains existing data structure:

{
  "data": {
    "marketId": "MKT001",
    "marketName": "Growth Market",
    "totalValue": 1500000.00,
    "performanceData": {
      "ytdReturn": 12.5,
      "annualizedReturn": 8.2
    }
  },
  "errorMessage": null
}

Financial Calculation Services

Financial calculation requests with custom authentication:

curl -v -H "bigdataToken: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
     -H "Content-Type: application/json" \
     -X POST \
     --data '{"calculationType":"netPresentValue","cashFlows":[100,200,300],"discountRate":0.05}' \
     http://localhost:8080/axis2/services/dataService/financialCalculation

Financial calculation response format:

{
  "data": {
    "calculationType": "netPresentValue",
    "result": 544.22,
    "calculationDetails": {
      "inputCashFlows": [100, 200, 300],
      "discountRate": 0.05,
      "periodCount": 3
    }
  },
  "errorMessage": null
}

Excel Integration - Function Metadata

Excel Add-in compatibility with function specification endpoints:

curl -v -H "bigdataToken: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
     -H "Content-Type: application/json" \
     -X GET \
     http://localhost:8080/axis2/services/excelService/functionSpecs

Response providing Excel function metadata:

{
  "data": {
    "functions": [
      {
        "name": "MARKET_VALUE",
        "description": "Get current market value",
        "parameters": ["marketId", "asOfDate"],
        "returnType": "number"
      },
      {
        "name": "FINANCIAL_CALC",
        "description": "Perform financial calculations",
        "parameters": ["calculationType", "parameters"],
        "returnType": "number"
      }
    ]
  },
  "errorMessage": null
}

Interactive Swagger UI

Access the interactive API documentation at:

http://localhost:8080/axis2/swagger-ui

The Swagger UI provides:

• Interactive Testing: Try API endpoints directly from the browser
• Authentication Support: Test with custom headers and tokens
• Request/Response Examples: See expected data formats
• Schema Documentation: Detailed model and parameter information

OpenAPI Specification Endpoints

Access the raw OpenAPI specifications:

# JSON format
http://localhost:8080/axis2/openapi.json

# YAML format (if supported)
http://localhost:8080/axis2/openapi.yaml

These endpoints are CORS-enabled for frontend integration and can be used by:

• Code Generation: Generate TypeScript/JavaScript clients
• API Testing: Import into Postman, Insomnia, or similar tools
• Documentation: Generate static documentation or integrate with docs systems

Migration Strategy

Follow this approach for seamless backend replacement:

1. API Analysis: Document existing endpoints, request/response formats, and authentication patterns
2. Service Implementation: Create Axis2 services matching existing API contracts
3. Configuration: Set up OpenAPI module with STATIC mode using existing schemas
4. Testing: Validate compatibility with existing frontend applications
5. Deployment: Replace backend services incrementally

Common Compatibility Patterns

Handle common frontend integration patterns:

// Support existing custom headers instead of standard Authorization
@HeaderParam("bigdataToken") String customToken
@HeaderParam("apiKey") String apiKey
@HeaderParam("sessionId") String sessionId

// Many frontends expect data/error envelope pattern
public class StandardResponse<T> {
    @Json(name = "data")
    private T data;

    @Json(name = "errorMessage")
    private String errorMessage;

    @Json(name = "success")
    private boolean success = true;
}

// Match existing URL patterns exactly
@Path("/api/v1/markets/{marketId}/summary")
@Path("/bigdataservice/calculate")  // Legacy path support
@Path("/excel/functions/{functionName}")

Frontend Integration Testing

Validate drop-in compatibility with these testing approaches:

• TypeScript Clients: Ensure generated clients work without modifications
• Excel Add-ins: Test Office.js integrations and custom function calls
• React/Angular Apps: Verify existing HTTP service layers continue working
• Mobile Apps: Test native HTTP clients and authentication flows

Configuration for Different Frameworks

Axis2 OpenAPI services can replace backends built with various frameworks:

# Spring Boot endpoint:
@PostMapping("/api/markets/summary")
public ResponseEntity<MarketResponse> getMarketSummary(@RequestBody MarketRequest request)

# Equivalent Axis2 service:
@POST
@Path("/api/markets/summary")
public MarketResponse getMarketSummary(MarketRequest request)

// Express.js endpoint:
app.post('/api/auth/login', (req, res) => { ... })

// Equivalent Axis2 service:
@POST
@Path("/api/auth/login")
public LoginResponse login(LoginRequest request)

// ASP.NET Core endpoint:
[HttpPost("/api/data/process")]
public ActionResult<DataResponse> ProcessData([FromBody] DataRequest request)

// Equivalent Axis2 service:
@POST
@Path("/api/data/process")
public DataResponse processData(DataRequest request)

Performance Optimizations

• JSON Processing: Choice of Moshi, Gson, or streaming formatters — each with HTTP/2-enhanced variants for large payloads
• Service Caching: OpenAPI spec generation results are cached for improved response times
• CORS Optimization: Efficient CORS header handling for browser-based applications
• Memory Management: Streaming support for large request/response payloads

Best Practices

• Schema Validation: Use OpenAPI schema validation for request/response verification
• Error Handling: Implement consistent error response formats across all services
• Authentication: Centralize token validation and user context management
• Monitoring: Implement service health checks and performance metrics
• Documentation: Keep OpenAPI schemas up-to-date with service changes

Security Considerations

Ensure secure REST API implementation:

• Input Validation: Validate all request parameters and payloads
• Authentication: Implement proper token validation and session management
• CORS Policy: Configure appropriate CORS policies for production environments
• HTTPS: Use HTTPS in production for secure data transmission
• Rate Limiting: Implement rate limiting to prevent API abuse

Module Loading Issues

If the OpenAPI module fails to load:

1. Verify the module is included in axis2.xml: <module ref="openapi" />
2. Check that openapi.mar is present in the modules directory
3. Review server logs for initialization errors

Swagger UI Access Problems

If Swagger UI is not accessible:

1. Confirm enableSwaggerUI parameter is set to true
2. Check the swaggerUIPath configuration
3. Verify CORS settings if accessing from a different domain

API Compatibility Issues

When replacing existing backends:

1. Compare request/response formats using API testing tools
2. Verify custom header handling and authentication patterns
3. Test with actual frontend applications, not just cURL
4. Review error response formats and status codes

Performance Issues

For performance optimization:

1. Monitor memory usage with large JSON payloads
2. Profile JSON serialization/deserialization performance
3. Review OpenAPI spec generation caching configuration
4. Check database connection pooling and query optimization

For additional support, contact the Axis2 community through the mailing lists or GitHub issues. The community welcomes contributions and feedback on the OpenAPI integration.