Skip to Main Content

ORDS, SODA & JSON in the Database

Announcement

For appeals, questions and feedback, please email oracle-forums_moderators_us@oracle.com

ORDS-generated OpenAPI far from complete

Plamen PetrovDec 6 2023 — edited Dec 6 2023

Hi,

It is great that ORDS auto-generates an OpenAPI specs, but … the result is far from desirbale. Just look at the classical example, https://petstore.swagger.io/, and what you get from your ORDS services! A small fraction of what could be a very detaild and useful documentation.

The test case:

-- Generated by Oracle SQL Developer REST Data Services 23.1.0.097.1607
-- Exported REST Definitions from ORDS Schema Version 23.1.4.r1501808
-- Schema: PPV   Date: Wed Dec 06 14:26:41 CET 2023
--
BEGIN
   ords.enable_schema(
       p_enabled             => TRUE,
       p_schema              => 'PPV',
       p_url_mapping_type    => 'BASE_PATH',
       p_url_mapping_pattern => 'ppv',
       p_auto_rest_auth      => FALSE);
   ords.define_module(
       p_module_name    => 'V2',
       p_base_path      => '/V2/',
       p_items_per_page => 25,
       p_status         => 'PUBLISHED',
       p_comments       => 'Module-level comment V2.');
   ords.define_template(
       p_module_name => 'V2',
       p_pattern     => 'demo_get',
       p_priority    => 0,
       p_etag_type   => 'HASH',
       p_etag_query  => NULL,
       p_comments    => 'Template-level comment demo_get');
   ords.define_handler(
       p_module_name    => 'V2',
       p_pattern        => 'demo_get',
       p_method         => 'GET',
       p_source_type    => 'json/collection',
       p_items_per_page => 25,
       p_mimes_allowed  => '',
       p_comments       => 'Handler-level comment GET.',
       p_source         => 'select * from dual where dummy = :demo_param'
   );
   ords.define_parameter(
       p_module_name        => 'V2',
       p_pattern            => 'demo_get',
       p_method             => 'GET',
       p_name               => 'demo_param',
       p_bind_variable_name => 'demo_param',
       p_source_type        => 'URI',
       p_param_type         => 'STRING',
       p_access_method      => 'IN',
       p_comments           => 'Parameter-level comment demo_param.');
   COMMIT;
END;

Note that I have used the p_comments paramter for all ORDS objects. The outcome of /ords/ppv/open-api-catalog/V2/ :

{
    "openapi": "3.0.0",
    "info": {
        "title": "ORDS generated API for V2",
        "version": "1.0.0"
    },
    "servers": [
        {
            "url": "https://...deleted.../V2/",
            "description": "Module-level comment V2."
        }
    ],
    "paths": {
        "/demo_get": {
            "get": {
                "description": "Handler-level comment GET.",
                "responses": {
                    "200": {
                        "description": "The queried record.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "items": {
                                            "type": "array",
                                            "items": {
                                                "type": "object",
                                                "properties": {
                                                    "dummy": {
                                                        "$ref": "#/components/schemas/VARCHAR2"
                                                    }
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "demo_param",
                        "in": "path",
                        "schema": {
                            "type": "string"
                        },
                        "required": true
                    }
                ]
            }
        }
    },
    "components": {
        "schemas": {
            "VARCHAR2": {
                "type": "string"
            }
        }
    }
}

Only the module- and handler-level commets made it to the OpenAPI file. and the Module comment went to the “server” section instead of the “info”. The Parameters comments are nowhere to be seen as well as the Template one. There is no way to replace the default “title”: “ORDS generated…”. There is no “tags” section - all services are grouped as “default" in Swagger, etc. etc.

Are these bugs or it is what it is? Are there alternative ways to generate the OpenAPI file or inject the missing sections into the auto-generated one?

Best,

Plamen

Comments
Post Details
Added on Dec 6 2023
2 comments
242 views