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 editor.swagger.io 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

https://www.oracle.com/technetwork/developer-tools/rest-data-services/downloads/ords-releasenotes-194-5908833.html

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 ords_modules.name%TYPE,
      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.

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 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         => 
'begin
insert into identity_table (words) values (:words);
commit;
end;'
      );
 
  COMMIT; 
END;
/

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

Ta-da!

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

thatjeffsmith
Author

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

Write A Comment