Updated 29 April 2022

You can easily generate documentation sets for your RESTful Services in ORDS using things like Swagger tools. REST Modules include a links for the OpenAPI 2.0 JSON specs.

It’s one OpenAPI link PER module.

But I want OpenAPI v3!!

Ok, just add this header to your request.

--header 'Accept: application/vnd.oai.openapi+json;version=3.0'
This will soon be the default response in ORDS.

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!

Or, new for ORDS 21, simply access the OpenAPI view directly from SQL Developer Web’s REST Workshop!

Use the Export fly-out to get the PL/SQL API code or the raw JSON OpenAPI representation.

Then that will take you here –

I talk more about this specific feature here.

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

A real-world customer example

Oli is a consultant in Iceland who loves ORDS. In fact, you can read his quote right at the top of our ORDS Product page on Oracle.com 🙂 We’re going to be publishing more on Oli’s story soon!

In the meantime, Oli shared on our Discord channel some cool things he’s achieved using this feature of ORDS.

ORDS Design Time…with the comments:

Nice documentation is critical for adoption of your REST APIs

Then ORDS at runtime, accessing the built-in OpenAPI view from the REST Workshop in SQL Developer Web:

Nice, right?

This same information will also appear in the Swagger clients which pull from the OpenAPI JSON for the module.

Author

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

7 Comments

  1. Rob de Gouw Reply

    Jeff,

    Is there still now way to get the OpenAPI 3.0 document for AutoREST objects?
    It woul dbe a nice addition, since Visual Builder can eat OpenAPI 3.0 format URL’s

    Kind regards,

    Rob

  2. 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.

  3. 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,
    Pieter

    • 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.

  4. 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!

    • 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