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.
