When I request the doc describing my endpoints, you have a few choices:
- metadata-catalog (Specific to ORDS)
- OpenAPI 2.0
- OpenAPI 3.0
Metadata Catalog
This was our first entry in cataloging what a schema has available in terms of ORDS REST APIs.
If you pull up
/ords/{schema}/metadata-catalog
You’ll get a list of modules and REST enabled objects.
There are a couple of links there. The first is just another metadata-catalog endpoint for a specific object or module –
OpenAPI 2.0
But the SECOND link mentioned for items in the metadata-catalog list is for
"rel": "alternate",
"href": "http://localhost:8080/ords/hr/open-api-catalog/HTP/",
"mediaType": "application/openapi+json"}
And when we follow THIS –
“swagger:”: “2.0”…but I want and NEED 3.0!
OpenAPI 3.0
This is currently a ‘trick’ – that is, it’s not documented. I’m having it added to the Docs now. And we’ll probably change the default from Swagger 2.0 to OpenAPI 3.0 later this year…
curl --request GET \
--url http://localhost:8080/ords/hr/open-api-catalog/autobeers/ \
--header 'Accept: application/vnd.oai.openapi+json;version=3.0'
Swagger, 2.0, 3.0, OpenAPI…I’m confused!
When someone asks for ‘Swagger,’ you might want to ask them, ‘2.0 or 3.0?’
TL;DR – ‘swagger’ = the tools. ‘OpenAPI’ = the specification used to describe REST APIs.
It’s very easy to conflate the YMAL/JSON you see as ‘swagger’ – be careful you’re talking about the same thing when working with others.
6 Comments
I’m seeing this error:
InternalServerException [statusCode=500, logLevel=SEVERE, reasons=[]]
at oracle.dbtools.rest.metadata.catalog.swagger.SwaggerModelGeneratorBase.handleMetadata(SwaggerModelGeneratorBase.java:189)
at oracle.dbtools.rest.metadata.catalog.swagger.SwaggerCatalogItemsServlet.doGet(SwaggerCatalogItemsServlet.java:54)
at javax.servlet.http.HttpServlet.service(HttpServlet.java:503)
at oracle.dbtools.plugin.api.servlet.HttpServletBase.service(HttpServletBase.java:86)
. . . .
Caused by: java.sql.SQLException: ORA-61708: Object “RECIPES”.”GET_RECIPES” cannot be described as a JSON schema.
ORA-06512: at “SYS.DBMS_JSON_SCHEMA”, line 237
ORA-06512: at “SYS.DBMS_JSON_SCHEMA”, line 280
ORA-06512: at line 1
Here is the DDL for that object GET_RECIPES and the table it references:
CREATE TABLE RECIPES.RECIPES
(
RECIPE_NAME VARCHAR2(100 BYTE)
) ;
CREATE OR REPLACE PROCEDURE RECIPES.GET_RECIPES (p_input_txt in varchar2, p_cursor out sys_refcursor) as
begin
open p_cursor for
select * from recipes;
end;
/
p_input_txt isn’t used at the moment, just trying to experiment with ORDS at the moment. Thank you!
Are you using AUTO plsql feature or did you hand code a module?
It’s AUTO — and I’ve tried enabling it different ways: from inside APEX, SQL Developer web, SQL developer desktop.
I was able to get everything to work by manually creating the module. I think for my use case I would ultimately be creating custom modules anyway. Below is the module exported:
BEGIN
ORDS.ENABLE_SCHEMA(
p_enabled => TRUE,
p_schema => ‘RECIPES’,
p_url_mapping_type => ‘BASE_PATH’,
p_url_mapping_pattern => ‘recipes’,
p_auto_rest_auth => FALSE);
ORDS.DEFINE_MODULE(
p_module_name => ‘testmodule’,
p_base_path => ‘/testmodule/’,
p_items_per_page => 25,
p_status => ‘PUBLISHED’,
p_comments => NULL);
ORDS.DEFINE_TEMPLATE(
p_module_name => ‘testmodule’,
p_pattern => ‘get_recipes’,
p_priority => 0,
p_etag_type => ‘HASH’,
p_etag_query => NULL,
p_comments => NULL);
ORDS.DEFINE_HANDLER(
p_module_name => ‘testmodule’,
p_pattern => ‘get_recipes’,
p_method => ‘GET’,
p_source_type => ‘plsql/block’,
p_items_per_page => 25,
p_mimes_allowed => NULL,
p_comments => NULL,
p_source =>
‘begin
GET_RECIPES(:txt, :results);
end;’);
ORDS.DEFINE_PARAMETER(
p_module_name => ‘testmodule’,
p_pattern => ‘get_recipes’,
p_method => ‘GET’,
p_name => ‘txt’,
p_bind_variable_name => ‘txt’,
p_source_type => ‘HEADER’,
p_param_type => ‘STRING’,
p_access_method => ‘IN’,
p_comments => NULL);
ORDS.DEFINE_PARAMETER(
p_module_name => ‘testmodule’,
p_pattern => ‘get_recipes’,
p_method => ‘GET’,
p_name => ‘results’,
p_bind_variable_name => ‘results’,
p_source_type => ‘RESPONSE’,
p_param_type => ‘RESULTSET’,
p_access_method => ‘OUT’,
p_comments => NULL);
Hi Jeff,
I can AutoREST enable stored procedures and functions and successfully call them with curl, returning output parameters, but I don’t see these objects show up in the Metadata Catalog. I do see my tables in the Metadata Catalog. Do you expect stored procedures and functions to show up there? Possibly related, I get an error 500 when trying to Export OpenAPI for these types of objects. Thanks!
On the ords backend log, there should be a ora/plsql error stack from that 500.
Can you find that, this screams bug.
Or if you have some plsql to share I can test with here locally.