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.
But I want OpenAPI v3!!
Ok, just add this header to your request.
--header 'Accept: application/vnd.oai.openapi+json;version=3.0'
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.
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.
Or, new for ORDS 21, simply access the OpenAPI view directly from SQL Developer Web’s REST Workshop!
Then that will take you 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:
Then ORDS at runtime, accessing the built-in OpenAPI view from the REST Workshop in SQL Developer Web:
This same information will also appear in the Swagger clients which pull from the OpenAPI JSON for the module.
7 Comments
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
Should be ready this Fall (21.3)
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.
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.
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.