An API is easier to use with a description that tools understand. ORDS generates an OpenAPI 3 document for every REST module, listing its paths, methods, parameters, and response shapes, and keeps it current as handlers change. Swagger UI, Postman, and code generators can read it directly. This guide fetches the document for a module, improves its descriptions, and views it in Swagger UI.
Before You Start
You need ORDS installed and running against your database, and a schema to work in. The examples use NIMBUS, the sample schema of a fictional airline, which you can install with the scripts in the setup/nimbus folder of the Oracle Database 26ai code repository on GitHub. The schema comes from Oracle Database 26ai SQL and PL/SQL Book.
ORDS in the examples answers at https://localhost:8443/ords/, and NIMBUS is REST-enabled with the URL alias nimbus. Replace the host and port with your own ORDS address. The curl commands use -k because the test server has a self-signed certificate; leave it out when your certificate is trusted. JSON responses are formatted for reading; ORDS returns them on one line.
The document describes the network module built in How to Create a REST Module, Template, and Handler with ORDS.DEFINE_MODULE and the guides after it.
Syntax
GET https://host:port/ords/schema_alias/open-api-catalog/ -- list GET https://host:port/ords/schema_alias/open-api-catalog/module_base_path/ -- one module
Comments given to ORDS.DEFINE_MODULE and ORDS.DEFINE_HANDLER become descriptions in the document.
Fetch the Document
Example:
curl -k https://localhost:8443/ords/nimbus/open-api-catalog/network/
Output (beginning of the document):
{
"openapi": "3.0.0",
"info": {
"title": "ORDS generated API for network",
"version": "1.0.0",
"description": "Nimbus Air route network"
},
"servers": [
{
"url": "https://localhost:8443/ords/nimbus/network"
}
],
"paths": {
"/airports/{code}/summary": {
"get": {
"description": "Retrieve a record from network",
"responses": {
"200": {
"description": "The queried record.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {}
}
}
}
}
},
"parameters": [
...The module's comment, Nimbus Air route network, is the API description, and the server URL is the module's base. Path parameters such as code appear as {code} with their own entry.
Describe an Operation
Without a comment, the routes GET operation is described as Retrieve records from network. Defining the handler again with p_comments sets a better description:
Example:
begin
ords.define_handler(p_module_name => 'network',
p_pattern => 'routes',
p_method => 'GET',
p_source_type => ords.source_type_collection_feed,
p_source => 'select route_id, origin, destination, distance_km
from routes
order by route_id',
p_comments => 'Lists every Nimbus Air route, 10 per page');
commit;
end;
/The /routes entry of the document now reads:
Output:
{
"paths": {
"/routes": {
"get": {
"description": "Lists every Nimbus Air route, 10 per page",
"responses": {
"200": {
"description": "The queried record.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"destination": {
"$ref": "#/components/schemas/CHAR"
},
"distance_km": {
"$ref": "#/components/schemas/NUMBER"
},
"origin": {
"$ref": "#/components/schemas/CHAR"
},
"route_id": {
"$ref": "#/components/schemas/NUMBER"
}
}
}
}
}
}
}
}
}
},
"parameters": []
}
}
}
}The collection's items schema lists the query's columns with their types.
View It in Swagger UI
Swagger UI loads the document from its URL and lists every operation of the module:
Things to Know
- The document of a protected module is not protected with it: in the test, /open-api-catalog/hr/ answered without a token although every /hr/ endpoint required one. The data stays protected; if the API's shape must stay private as well, add and test a privilege mapping for that path.
- The document follows the definitions in the database, so it is current after every change, once ORDS refreshes its cache.
- Parameters declared with ORDS.DEFINE_PARAMETER appear with their types: min_km of routes/from/{origin} is listed as an integer, though as a path parameter, because its source type is URI. Undeclared query-string parameters do not appear.
Related Guides
Conclusion
ORDS publishes an OpenAPI 3 document for every module at open-api-catalog. Add comments to modules and handlers for readable descriptions, declare parameters for typed documentation, and point Swagger UI or Postman at the URL.
