Customizing the Oracle ORDS generated Swagger documentation

Question

I'm writing a REST-API using Oracle ORDS. ORDS generates a Swagger 2.0 API documentation on a predefined URL.

I can not find how to add custom information like a text for the endpoint description or the name and schema for the "object" returned from the endpoint.

Does anyone here know how to adjust the ORDS generated Swagger documentation?

thatjeffsmith thatjeffsmith · Accepted Answer · 2020-02-11T12:48:26

We recently enhanced ORDS such that you could inject custom comments into the Swagger-style OpenAPI Docs.

New Features in 18.4.0

ENH:28028432 - Echo p_comments value into generated Swagger documentation Earlier versions

Here's an example -

Defining my POST

BEGIN
  ORDS.DEFINE_HANDLER(
      p_module_name    => 'EXAMPLES',
      p_pattern        => 'id/',
      p_method         => 'POST',
      p_source_type    => 'plsql/block',
      p_items_per_page =>  0,
      p_mimes_allowed  => 'application/json',
      p_comments       => 'This is a bad example, has no error handling',
      p_source         => 
'begin
insert into identity_table (words) values (:words);
commit;
end;'
      );

  COMMIT; 
END;
/

Now if I go to the OpenAPI endpoint for my module, you can see the Description text for the handler has been 'injected' into the service documentation.

"This is a bad example, has no error handling" -- it's a free text field, so you can basically put anything you want there.

{
"swagger": "2.0",
"info": {
"title": "ORDS generated API for EXAMPLES",
"version": "1.0.0"
},
"host": "localhost:8080",
"basePath": "/ords/pdb2/jeff/examples",
"schemes": [
"http"
],
"produces": [
"application/json"
],
"paths": {
"/id/": {
"get": {
"description": "Retrieve records from EXAMPLES",
"produces": [
"application/json"
],
"responses": {
"200": {
"description": "The queried record.",
"schema": {
"type": "object",
"properties": {
"ID": {
"$ref": "#/definitions/NUMBER"
},
"WORDS": {
"$ref": "#/definitions/VARCHAR2"
}
}
}
}
},
"parameters": []
},
"post": {
"description": "This is a bad example, has no error handling",
"responses": {
"201": {
"description": "The successfully created record.",
"schema": {
"type": "object",
"properties": {}
}
}
},
"consumes": [
"application/json"
],
"parameters": [
{
"name": "payload",
"in": "body",
"required": true,
"schema": {
"$ref": "#/definitions/EXAMPLES_ITEM"
}
}
]
}
},
"/id/{pk}": {
"get": {
"description": "Retrieve records from EXAMPLES",
"produces": [
"application/json"
],
"responses": {
"200": {
"description": "The queried record.",
"schema": {
"type": "object",
"properties": {
"ID": {
"$ref": "#/definitions/NUMBER"
},
"WORDS": {
"$ref": "#/definitions/VARCHAR2"
}
}
}
}
},
"parameters": [
{
"name": "pk",
"in": "path",
"required": true,
"type": "string",
"description": "implicit",
"pattern": "^[^/]+$"
}
]
}
}
},
"definitions": {
"NUMBER": {
"type": "number"
},
"VARCHAR2": {
"type": "string"
},
"EXAMPLES_ITEM": {
"properties": {
"words": {
"type": "string"
}
}
}
}
}

Customizing the Oracle ORDS generated Swagger documentation

1 Answers