8i | 9i | 10g | 11g | 12c | 13c | 18c | 19c | 21c | 23c | Misc | PL/SQL | SQL | RAC | WebLogic | Linux

Home » Articles » Misc » Here

Oracle REST Data Services (ORDS) : Open API 2.0 and 3.0 (Swagger) Support

The Open API Initiative (OAI) provides an open specification, originally know as the Swagger specification, for describing and documenting REST APIs. From version 17.4 onward, Oracle REST Data Services (ORDS) exposes the metadata of specific web services in Open API 2.0 format, making it easy to document and generate calling code for REST APIs using Swagger. From version 22.1, ORDS also supports Open API 3.0 format, and from version 22.2 the default format is Open API 3.0.

Related articles.

Setup

The examples in this article are based the following.

Metadata Catalog

Using ORDS 17.4 onward the top-level metadata-catalog output includes both the original metadata-catalog and open-api-catalog URLs of all relevant objects in an ORDS enabled schema. The metadata-catalog output for a specific object is presented in the original format, while the open-api-catalog output is in Open API (Swagger) 2.0 format, which makes it really simple to generate documentation and an example of the calling code in several programming languages. From ORDS version 22.2 the default format is Open API 3.0.

An overview of the contents of an ORDS enabled schema can be displayed in a browser (GET HTTP method) using the following type of URL. The output is a JSON document.

Both URL types listed.
Format  : https://server:port/ords/<connection>/<schema-alias>/metadata-catalog/
Example : https://localhost:8443/ords/testuser1/metadata-catalog/

Open API URLs listed
Format  : https://server:port/ords/<connection>/<schema-alias>/open-api-catalog/
Example : https://localhost:8443/ords/testuser1/open-api-catalog/

The open-api-catalog output for a specific service is displayed in the Open API 2.0 format.

Open API Format
Format  : https://server:port/ords/<connection>/<schema-alias>/open-api-catalog/<object-alias>/
Example : https://localhost:8443/ords/testuser1/open-api-catalog/testmodule3/

Example 1 : Manually Created RESTful Service

We can use a browser, REST client or the curl command to check the metadata for the testmodule3 module using the object alias associated with the module, also testmodule3 in this case. Here is an example using the curl command.

$ curl -k "https://localhost:8443/ords/testuser1/open-api-catalog/testmodule3/"

{"swagger":"2.0","info":{"title":"ORDS generated API for testmodule3","version":"1.0.0"},"host":"localhost:8443",
"basePath":"/ords/testuser1/testmodule3","schemes":["http"],"produces":["application/json"],
"paths":{"/emp/":{"get":{"produces":["application/json"],"responses":{"200":{"description":"output of the endpoint",
"schema":{"type":"object","properties":{}}}}}},"/emp/{empno}":{"get":{"produces":["application/json"],
"responses":{"200":{"description":"output of the endpoint","schema":{"type":"object","properties":{}}}},
"parameters":[{"name":"empno","in":"path","required":true,"type":"string","description":"implicit","pattern":"^[^/]+$"}]}}}}

If we go to the online Swagger Editor, we can paste in the output JSON text, which converts to YAML and displays the available endpoints.

Swagger Editor - Description 1

The "Generate Client" menu at the top of the screen allows us to create client code to call this service from a number of different languages.

Swagger Editor - Client Code

The sample code is downloaded as a zip file.

Example 2 : AutoREST Service

We can display the metadata for the table EMP, which is AutoREST enabled, using the following curl command.

$ curl -k "https://localhost:8443/ords/testuser1/open-api-catalog/employees/"

{"swagger":"2.0","info":{"title":"ORDS generated API for EMP","version":"1.0.0"},
"host":"localhost:8443","basePath":"/ords/testuser1/employees",
"schemes":["http"],"produces":["application/json"],"paths":{"/":{"get":{"produces":["application/json"],
"responses":{"200":{"description":"output of the endpoint","schema":{"type":"object","properties":{}}}}},
"post":{"produces":["application/json"],"responses":{"200":{"description":"output of the endpoint",
"schema":{"type":"object","properties":{}}}},"parameters":[{"name":"payload","in":"body","required":true,
"schema":{"$ref":"#/definitions/PAYLOAD1"}}]}},"/{id}":{"get":{"produces":["application/json"],
"responses":{"200":{"description":"output of the endpoint","schema":{"type":"object","properties":{}}}},
"parameters":[{"name":"id","in":"path","required":true,"type":"string","description":"implicit",
"pattern":"^[^/]+$"}]},"put":{"produces":["application/json"],"responses":{"200":{"description":"output of the endpoint",
"schema":{"type":"object","properties":{}}}},"parameters":[{"name":"id","in":"path","required":true,"type":"string",
"description":"implicit","pattern":"^[^/]+$"},{"name":"payload","in":"body","required":true,
"schema":{"$ref":"#/definitions/PAYLOAD1"}}]},"delete":{"produces":["application/json"],
"responses":{"200":{"description":"output of the endpoint","schema":{"type":"object","properties":{}}}},
"parameters":[{"name":"id","in":"path","required":true,"type":"string","description":"implicit",
"pattern":"^[^/]+$"}]}}},"definitions":{"DATE":{"type":"string",
"pattern":"^\\d{4}-[01]\\d-[0123]\\dT[012]\\d:[0-5]\\d:[0-5]\\d(.\\d+)?(Z|([-+][012]\\d:[0-5]\\d))$"},
"NUMBER":{"type":"number"},"VARCHAR2":{"type":"string"},"PAYLOAD1":{"properties":{"EMPNO":{"$ref":"#/definitions/NUMBER"},
"ENAME":{"$ref":"#/definitions/VARCHAR2"},"JOB":{"$ref":"#/definitions/VARCHAR2"},"MGR":{"$ref":"#/definitions/NUMBER"},
"HIREDATE":{"$ref":"#/definitions/DATE"},"SAL":{"$ref":"#/definitions/NUMBER"},"COMM":{"$ref":"#/definitions/NUMBER"},
"DEPTNO":{"$ref":"#/definitions/NUMBER"}}}}}

After pasting the output into the Swagger Editor we see a larger number of endpoints, as well as a payload definition for those endpoints that require it.

Swagger Editor - Description 2

As before, sample calling code for this service can be generated from the "Generate Client" menu.

Open API 3.0

From version 22.1 ORDS can also display metadata in Open API 3.0 format. From ORDS version 22.2 the default format is Open API 3.0, so you don't need to add the extra parameters. We make the same type of call as before, but add some extra header information.

$ curl -k "https://localhost:8443/ords/testuser1/open-api-catalog/employees/" --header 'Accept: application/vnd.oai.openapi+json;version=3.0'

{"openapi":"3.0.0","info":{"title":"ORDS generated API for EMP","version":"1.0.0"},
"servers":[{"url":"https://localhost:8443/ords/testuser1/employees/"}],
"paths":{"/":{"get":{"description":"Retrieve records from EMP",
"responses":{"200":{"description":"The queried record.",
"content":{"application/json":{"schema":{"type":"object",
"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/EMP_ITEM"}}}}}}}}},
"post":{"description":"Create a new record on EMP","responses":{"201":{"description":"The successfully created record.",
"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EMP_ITEM"}}}}},
"parameters":[],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EMP_ITEM"}}}}}},
"/batchload":{"post":{"description":"Create new records on EMP",
"responses":{"200":{"description":"The status of the processed records.",
"content":{"application/json":{"schema":{"type":"string"}}}}},"parameters":[],
"requestBody":{"content":{"text/csv":{"schema":{}}}}}},
"/{id}":{"delete":{"description":"Remove a record from EMP",
"responses":{"204":{"description":"Deleted result.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EMP_ITEM"}}}}},
"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[^/]+$"},
"description":"implicit"}]},"get":{"description":"Retrieve a record from EMP",
"responses":{"200":{"description":"The queried record.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EMP_ITEM"}}}}},
"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[^/]+$"},
"description":"implicit"}]},"put":{"description":"Create or update a record on EMP",
"responses":{"201":{"description":"The successfully created record.",
"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EMP_ITEM"}}}},
"200":{"description":"The successfully updated record.",
"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EMP_ITEM"}}}}},"parameters":[{"name":"id","in":"path",
"required":true,"schema":{"type":"string","pattern":"^[^/]+$"},"description":"implicit"}],
"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EMP_ITEM"}}}}}}},
"components":{"schemas":{"DATE":{"type":"string","format":"date-time","pattern":"^\\d{4}-[01]\\d-[0123]\\dT[012]\\d:[0-5]\\d:[0-5]\\d(.\\d+)?(Z|([-+][012]\\d:[0-5]\\d))$"},
"NUMBER":{"type":"number"},"VARCHAR2":{"type":"string"},
"EMP_ITEM":{"properties":{"comm":{"$ref":"#/components/schemas/NUMBER"},
"deptno":{"$ref":"#/components/schemas/NUMBER"},"empno":{"$ref":"#/components/schemas/NUMBER"},
"ename":{"$ref":"#/components/schemas/VARCHAR2"},"hiredate":{"$ref":"#/components/schemas/DATE"},
"job":{"$ref":"#/components/schemas/VARCHAR2"},"mgr":{"$ref":"#/components/schemas/NUMBER"},"sal":{"$ref":"#/components/schemas/NUMBER"}}}}}}

After pasting the output into the Swagger Editor we see the endpoints and a payload definition.

Swagger Editor - Description 3

For more information see:

Hope this helps. Regards Tim...

Back to the Top.