Key OpenAPI Features

• Automatic Generation: The specification is generated by introspecting the deployed Axis2 services; an OpenApiCustomizer can modify the generated document
• Interactive Documentation: Swagger UI (served at /swagger-ui) for API testing and exploration
• Standard Endpoints: OpenAPI specifications served at /openapi.json and /openapi.yaml, and an MCP tool catalog at /openapi-mcp.json
• CORS Headers: The specification and Swagger UI responses carry permissive CORS headers for browser-based tools
• Service Discovery: Automatic detection of REST-enabled Axis2 services
• Drop-in Compatibility: Designed to replace existing REST backends without frontend changes

Customizing the Generated Specification

The OpenAPI module always generates the specification from the deployed services; it does not serve a hand-written schema file in place of the generated one. To change the generated document (add servers, security schemes, descriptions or extra schemas), implement org.apache.axis2.openapi.OpenApiCustomizer and register it on the OpenApiConfiguration. See the OpenAPI Advanced User Guide for details.

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 contains one service:

• AuthenticationService: POST /bigdataservice/login, login with custom token generation. For demonstration it accepts any well-formed email address with the credentials demo.

The reference contract financial-api-schema.json also describes /bigdataservice/funds/summary, /bigdataservice/assets/calculate and /bigdataservice/user/*; these are not implemented by the sample. The data, calculation and Excel services shown below are illustrative patterns for your own services.

Authentication Service

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

@Path("/bigdataservice")
@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 with email and password, returns JWT token on success")
    public Response authenticateUser(LoginRequest loginRequest) {
        // Token generation and validation logic
    }
}

Data Service

An illustrative data service with authenticated endpoints (not part of the sample):

@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

Configuration is read from an openapi.properties file on the classpath, and any of the same keys may be overridden with Java system properties (for example -Dopenapi.title=...). The supported keys are:

• openapi.title, openapi.description, openapi.version, openapi.termsOfServiceUrl: API information in the generated specification
• openapi.contact.name, openapi.contact.email, openapi.contact.url: contact information
• openapi.license.name, openapi.license.url: license information
• openapi.serverBaseUrl: absolute URL to publish in servers[].url; by default a relative URL is published rather than one derived from the request
• openapi.prettyPrint: pretty-print the generated JSON
• openapi.swaggerUi.enabled: enable the Swagger UI page (default: true)
• openapi.swaggerUi.version, openapi.swaggerUi.integrity.bundle, openapi.swaggerUi.integrity.standalonePreset: the Swagger UI version loaded from the CDN (default 5.32.13) and the Subresource Integrity hashes for a non-default version
• openapi.resourcePackages, openapi.readAllResources: which resource classes to scan
• openapi.ignoredServices, openapi.ignoredOperations, openapi.ignoredRoutes: comma-separated services, operations (ServiceName/opName or opName) and path patterns to leave out of the specification

The module.xml inside the .mar also accepts the parameters title, version, description, prettyPrint, supportSwaggerUi and propertiesFile (the name of an additional properties file to load).

Authentication - Custom Token Pattern

Login request maintaining existing frontend patterns:

curl -v -H "Content-Type: application/json" \
     -X POST \
     --data '{"email":"[email protected]","credentials":"demo"}' \
     http://localhost:8080/axis2/services/authService/login

Response format compatible with existing frontends:

{
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "userId": "user123",
    "email": "[email protected]"
  },
  "errorMessage": null
}

Data Services - Custom Header Authentication

Data requests using a custom bigdataToken header (maintaining frontend compatibility). This and the following examples illustrate patterns for your own services; the sample does not implement them:

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 the path where the OpenAPI servlet is mapped, for example:

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
http://localhost:8080/axis2/openapi.yaml

# MCP tool catalog
http://localhost:8080/axis2/openapi-mcp.json

The specification endpoints send CORS headers 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: Engage the OpenAPI module and compare the generated specification with your existing schema, adjusting it with an OpenApiCustomizer where needed
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
• HTTP Caching: Specification responses carry a short Cache-Control max-age, and static Swagger UI resources a longer one
• 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 the openapi .mar file 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 openapi.swaggerUi.enabled is not set to false
2. Check that a servlet delegating to SwaggerUIHandler is mapped at /swagger-ui
3. If the page loads but stays blank, check that the browser can reach the Swagger UI CDN

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