Mostly Making oracle easy, mostly:
  • ORDS & SQL Developer Web 22.4.2 – Self Service Schemas
  • Generating DDL for your Oracle objects in SQL Developer Web
  • Hours wasted watching Grey’s Anatomy? Finding out with SQL!
  • Learning SQL using Spotify II: Functions, Group By, & Dates
  • Learning SQL with your own Spotify Streaming History data
  • Troubleshooting ORDS startup errors, the pool is invalid.
  • Create a ORDS REST API in a single PL/SQL call
  • Physical Properties in Oracle TABLE Liquibase changeSets
Search for:
  • Twitter
  • YouTube
  • LinkedIn
ThatJeffSmith ThatJeffSmith
  • SQL Developer
  • SQL Developer Web
  • REST APIs
  • Data Modeling
  • Ask A Question
  • About
In ORDS

Getting the OpenAPI Specs for your ORDS APIs, 2.0 or 3.0!

April 4, 2022 2 Mins Read

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.

I use this endpoint to debug 404’s – does ORDS even KNOW about your endpoint?

There are a couple of links there. The first is just another metadata-catalog endpoint for a specific object or module –

For a table, lists the Primary Key, columns, and data types.

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 –

This is much more interesting AND usable.

“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…

The Trick is in that Accept header.
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!

Read this, it will help.

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.

metadata-catalogopenapiORDSrestswagger
thatjeffsmith
Author thatjeffsmith

I'm a Distinguished Product Manager at Oracle. My mission is to help you and your company be more efficient with our database tools.

  • Website
Prev Post

Using SQL Developer Web to Test POST Handler REST APIs

April 4, 2022 2 Mins Read
Next Post

Oracle SQLcl 22.1 is now available & featuring Data Guard!

April 6, 2022 3 Mins Read

Related Posts

ORDS & SQL Developer Web 22.4.2 – Self Service Schemas

January 31, 2023

Troubleshooting ORDS startup errors, the pool is invalid.

January 10, 2023

Create a ORDS REST API in a single PL/SQL call

January 6, 2023
oracle sqlcl argument command for defining default values in sql scripts

ORDS & SQLcl 22.4 are now available for download

December 12, 2022

Cloud World 2022: Database Tools Tips & Tricks Video

November 29, 2022

Tuning REST APIs for Oracle Database – it’s probably the SQL

November 2, 2022

Write A Comment Cancel Reply

  • Search 1,000+ posts
  • What it is I do here

    I'm a product manager at Oracle, and
    I publish weekly - tips and tricks for Oracle SQL Developer, SQLcl, SQL Developer Data Modeler, and Oracle REST Data Services.

    Twitter YouTube LinkedIn
  • Your Favorite Posts
    • How to Import from Excel to Oracle with SQL Developer
    • Keyboard Shortcuts in Oracle SQL Developer
    • Enabling DBMS_OUTPUT by default in SQL Developer
    • Top 10 Preferences to Tweak when using SQL Developer
    • Formatting Query Results to CSV in Oracle SQL Developer
    • How To: Generate an ERD for Selected Tables in SQL Developer
    • Resetting Your Oracle User Password with SQL Developer
    • Die! Or How to Cancel Queries in Oracle SQL Developer
  • Enter your email address
  • Mostly Making Oracle Easy, Mostly

    Privacy Policy 

  • Mastodon
  • Twitter
  • YouTube
  • LinkedIn
  • Download SQL Developer
  • Developer Tools Message Boards

The views expressed on this blog are my own and do not necessarily reflect the views of Oracle. © Jeff Smith and ThatJeffSmith, 2021

Top
ThatJeffSmith