axis2-openapi — OpenAPI Integration Module

Auto-generates OpenAPI 3.0.1 specifications from deployed Axis2 services and serves Swagger UI at /swagger-ui.

Endpoints

Enabling the module

Add to WEB-INF/conf/axis2.xml:

<module ref="openapi"/>

Copy axis2-openapi-<version>.jar to WEB-INF/modules/openapi-<version>.mar.

Configuration

Configuration is loaded in this order (later sources win):

1. module.xml parameters
2. openapi.properties on the classpath (or the path set by propertiesFile module param)
3. Known locations: META-INF/openapi.properties, WEB-INF/openapi.properties, openapi-config.properties
4. System properties (same key names)
5. Programmatic OpenApiConfiguration API (highest precedence)

API information

Generation flags

Filtering: excluding services and operations

Three independent mechanisms control what appears in the generated spec. All are evaluated before inclusion rules — an excluded entity never appears even if it would otherwise match readAllResources or resourcePackages.

1. ignoredServices — exclude entire services by name

Matches against AxisService.getName() (exact, case-sensitive).

Properties file:

# Comma-separated list of service names to exclude
openapi.ignoredServices=InternalService, DebugService, AdminService

Java API:

OpenApiConfiguration config = new OpenApiConfiguration();
config.addIgnoredService("InternalService");
config.addIgnoredService("DebugService");

2. ignoredOperations — exclude specific operations

Each entry is one of:

Properties file:

# Targeted: remove one op from one service
# Global: remove an op name from all services
openapi.ignoredOperations=AdminService/nukeDatabase, internalStatus, debugPing

Java API:

config.addIgnoredOperation("AdminService/nukeDatabase");  // targeted
config.addIgnoredOperation("internalStatus");             // global (all services)

3. ignoredRoutes — exclude by generated path pattern

Matches against the generated path string (e.g. /services/MyService/myOp). Each entry is tested as a Java regex (String.matches()) or a substring (String.contains()).

openapi.ignoredRoutes=/services/internal/.*, /services/legacy/.*

Java API:

config.addIgnoredRoute("/services/internal/.*");

Prefer ignoredServices and ignoredOperations over ignoredRoutes — they match on logical names rather than generated path strings and are unaffected by future path format changes.

Precedence within the generator

isSystemService()          (hardcoded: Version, AdminService, __)
  → ignoredServices
    → readAllResources / resourceClasses / resourcePackages
      → shouldIncludeOperation() / ignoredOperations
        → isIgnoredRoute() / ignoredRoutes
          → (path added to spec)

Complete openapi.properties example

Place on the classpath as openapi.properties (or META-INF/openapi.properties):

# API identity
openapi.title=My Financial API
openapi.version=2.1.0
openapi.description=Internal portfolio management services

# Contact / license
openapi.contact.name=Platform Team
openapi.contact.email=platform@example.com
openapi.license.name=Proprietary

# Service filtering
openapi.ignoredServices=LegacySOAPService, InternalHealthCheck
openapi.ignoredOperations=AdminService/resetDatabase, debugEcho

# UI
openapi.prettyPrint=true
openapi.swaggerUi.enabled=true
openapi.swaggerUi.version=4.15.5

Programmatic configuration (Java)

OpenApiConfiguration config = new OpenApiConfiguration();

// API info
config.setTitle("My API");
config.setVersion("2.0.0");

// Exclude services
config.addIgnoredService("InternalService");

// Exclude operations
config.addIgnoredOperation("AdminService/nukeDatabase"); // this service only
config.addIgnoredOperation("debugPing");                 // all services

// Pass to the generator
OpenApiSpecGenerator generator = new OpenApiSpecGenerator(configContext, config);
String json = generator.generateOpenApiJson(httpRequest);
String yaml = generator.generateOpenApiYaml(httpRequest);

Known limitations

• Request body schema — all operations are typed as object because Axis2 JSON-RPC services use JsonRpcMessageReceiver and have no annotation-level parameter metadata. Schema details must be added via OpenApiCustomizer or by serving a static schema file.
• GET operations — all operations are mapped to POST; override via OpenApiCustomizer if GET endpoints are needed.
• YAML format — delegates to io.swagger.v3.core.util.Yaml, which uses jackson-dataformat-yaml internally; no additional dependency required.