1

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?

1 Answer 1

1

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.

enter image description here

{
"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"
}
}
}
}
}
3
  • Thanks :-) Then I just need to get the DB team to upgrade ORDS. Have you got any pointers for documenting the returned JSON structure also? Commented Feb 11, 2020 at 13:28
  • No @SamuelÅslund but you have 4,000 characters you can shove into the COMMENTS field, and if you use MarkDown it could look quite nice. Is there a particular json attribute that's not clear? Commented Feb 11, 2020 at 14:04
  • 2
    Swagger documents the response body swagger.io/docs/specification/2-0/describing-responses I would really like to know how to specify the "schema" and/or how to add to the swagger "definitions" like the "ORDS.ENABLE_OBJECT" does. I'd like to be able to show the Frontend people the format of data to expect from the endpoint Commented Feb 13, 2020 at 10:19

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.