You can easily generate {Swagger} documentation sets for your RESTful Services in ORDS. Each /metadata-catalog endpoint includes a link to get the OpenAPI 2.0 JSON as well.

It’s one OpenAPI link PER module.

We’ll generate the doc for you, and you can put it over to something like to get some nice Doc and Test clients for your Services.

Cool, right?

How to add your OWN text

Starting with version 18.4, your ORDS PL/SQL API calls for defining handlers has included the text you provide to P_COMMENTS with your OpenAPI responses.

ENH:28028432 – Echo p_comments value into generated Swagger documentation

Here’s the PACKAGE SPEC implementation of ORDS.DEFINE_HANDLER()

   * @param p_items_per_page  The DEFAULT pagination FOR a resource handler HTTP operation GET method, that IS, the NUMBER OF rows TO RETURN ON each page OF a JSON format result SET based ON a database query. DEFAULT: NULL (defers TO the resource module setting).
   * @param p_mimes_allowed   A comma separated list OF MIME types that the handler will accept. Applies TO PUT AND POST only.
   * @param p_comments        Commentary text.
  PROCEDURE define_handler(
      p_module_name        IN,
      p_pattern            IN ords_templates.uri_template%TYPE,
      p_method             IN ords_handlers.method%TYPE DEFAULT 'GET',
      p_source_type        IN ords_handlers.source_type%TYPE DEFAULT ords.source_type_collection_feed,
      p_source             IN ords_handlers.source%TYPE,
      p_items_per_page     IN ords_handlers.items_per_page%TYPE DEFAULT NULL,
      p_mimes_allowed      IN ords_handlers.mimes_allowed%TYPE DEFAULT NULL,
      p_comments           IN ords_handlers.comments%TYPE DEFAULT NULL);

If you pull up the ORDS.HANDLERS table, you’ll see that the COMMENTS table is a VARCHAR2(4000).

So, if I want to be nice, I can put some MarkDown in that field, let’s give it a try.

      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 for a PL/SQL REST Service**
It has no exception handling - and the INSERT should probably be a TABLE API PL/SQL call. However.
**Look how *easy* it is to access the JSON values**
Simply refer to the POST BODY attribute name using :bind style notation. You can get the value of {"something":"data"} by simply using :something in your SQL or PL/SQL code block for the HANDLER.',
      p_source         => 
insert into identity_table (words) values (:words);

Now let’s take the {JSON} response from the OpenAPI endpoint and put it over into


So as Blockbuster used to say, back in the day – Be Kind, Document your APIs!


I'm a Distinguished Product Manager at Oracle. My mission is to help you and your company be more efficient with our database tools.


  1. Avatar

    Can we improve documentation for AutoREST services too i.e. add comments for attributes and service level descriptions. I tried to add comments in the table and did AutoREST. But i am not seeing any those table column level comments in open api documentation.

  2. Avatar

    Hi Jeff,

    After adding p_comments to ORDS.DEFINE_MODULE or ORDS.DEFINE_HANDLER, the generated open-api-catalog for the module contains the inserted comments. So far, so good.

    Problem is that when you re-generate the REST definition from SQL Developer (e.g. right click on the module –> REST definition –> Save to worksheet) then the generated definition does not include the comments. The exported definition shows p_comments => NULL.

    It would be good if the actual p_comments value could be retained during the export.

    Kind regards,

    • Avatar

      Just wanted to add that the export of the REST definition works correctly when done from SQLcl. When using SQLcl it does show the correct p_comments. So the behavior above seems a bug in SQLDeveloper only.

  3. Avatar

    Does ORDS only auto generate Swagger documentation for “AutoREST Enabled” services, or can it also do the same for “Manually” created REST services? Also, you mention the link to get the OpenAPI 2.0 JSON is provided by ORDS, but in the screenshot it looks like you have the OpenAPI “3.0” JSON. Can you clarify this? Thanks!

    • thatjeffsmith

      I didn’t choose the best screenshot. The DB API json payload is for OpenAPI 3.0, the ones from rest enabled objects and restful services (yes, we generate for BOTH), are still v2.0.

Write A Comment