Oracle ORDS OpenAPI and Swagger Documentation for Your REST APIs

Self-Documenting APIs

ORDS can automatically generate OpenAPI (Swagger) documentation for your REST modules. This documentation describes every endpoint, its parameters, request/response formats, and authentication requirements in a standard format that tools like Swagger UI, Postman, and code generators understand. Well-documented APIs are easier to consume, test, and maintain.

Enabling OpenAPI in ORDS

ORDS generates OpenAPI metadata for your REST modules automatically. Access it at:

-- OpenAPI 3.0 JSON spec for your schema
GET /ords/{schema}/open-api-catalog/

-- Swagger UI (if enabled in ORDS configuration)
GET /ords/{schema}/open-api-catalog/swagger-ui/

Enriching Documentation With Metadata

ORDS generates basic documentation from your module definitions, but you can enrich it with descriptions, parameter details, and response examples:

BEGIN
    ORDS.DEFINE_MODULE(
        p_module_name => 'products',
        p_base_path   => '/api/v1/',
        p_items_per_page => 25,
        p_comments    => 'Product management API for the catalog application'
    );

    ORDS.DEFINE_TEMPLATE(
        p_module_name => 'products',
        p_pattern     => 'products/',
        p_comments    => 'Operations on the product collection'
    );

    ORDS.DEFINE_HANDLER(
        p_module_name => 'products',
        p_pattern     => 'products/',
        p_method      => 'GET',
        p_source_type => ORDS.SOURCE_TYPE_COLLECTION_FEED,
        p_comments    => 'Returns a paginated list of active products. '
                      || 'Supports filtering by category and price range.',
        p_source      => 'SELECT product_id, product_name, category, unit_price
                            FROM products WHERE status = ''ACTIVE''
                           ORDER BY product_name'
    );

    ORDS.DEFINE_PARAMETER(
        p_module_name  => 'products',
        p_pattern      => 'products/',
        p_method       => 'GET',
        p_name         => 'category',
        p_bind_variable_name => 'category',
        p_source_type  => 'URI',
        p_param_type   => 'STRING',
        p_access_method => 'IN',
        p_comments     => 'Filter products by category name'
    );
    COMMIT;
END;

Consuming the OpenAPI Spec

Give the OpenAPI URL to API consumers so they can import it into Postman for testing. Use code generators (swagger-codegen, openapi-generator) to create client SDKs in JavaScript, Python, Java, or any other language. Embed the Swagger UI page in your developer portal for interactive documentation that lets consumers try API calls directly from the browser.

Versioning Your API

Include a version number in your base path (/api/v1/, /api/v2/). When you need to make breaking changes, create a new version while keeping the old one running. The OpenAPI spec for each version is independent, so consumers can migrate at their own pace. Document deprecation timelines in the API description so consumers know when old versions will be retired.