Automate export of a Scripted REST API to OpenAPI YAML file

[Andy Kreider]

Is there any way to programmatically export the OpenAPI yaml file of a specific Scripted REST API?  We would like to export the API yaml so that we can include our ServiceNow APIs in a dictionary with other non-ServiceNow APIs for engineers to find when searching.  I know how to manually export the OpenAPI yaml file using the REST API Explorer.  I want to generate this file automatically.  Ideally, it would get generated any time the API was updated.

[Akshay Gupta2 · Accepted solution]

Hi @Andy Kreider 

Yes, there is a way to programmatically export the OpenAPI YAML file of a specific Scripted REST API. You can use the sn_rest_api_explorer.export_openapi_yaml method. This method takes a single parameter, which is the sys_id of the Scripted REST API.

Here is an example of how to use the sn_rest_api_explorer.export_openapi_yaml method:

var apiSysId = '<<sys_id of the Scripted REST API>>';
var openapiYaml = sn_rest_api_explorer.export_openapi_yaml(apiSysId);

The openapiYaml variable will now contain the OpenAPI YAML for the specified Scripted REST API. You can then use this YAML to include your ServiceNow APIs in a dictionary with other non-ServiceNow APIs for engineers to find when searching.

You can also use the sn_rest_api_explorer.export_openapi_yaml method to generate the OpenAPI YAML file automatically any time the API is updated. To do this, you can create a business rule on the sys_script_include table. The business rule should run the following script:

(function executeRule(current, previous /*null when async*/) {

  // Get the sys_id of the Scripted REST API
  var apiSysId = current.sys_id;

  // Export the OpenAPI YAML for the Scripted REST API
  var openapiYaml = sn_rest_api_explorer.export_openapi_yaml(apiSysId);

  // Save the OpenAPI YAML to a file
  var fileName = 'openapi.yaml';
  var file = new File(fileName);
  file.write(openapiYaml);
  file.save();

})(current, previous);

This business rule will run every time the Scripted REST API is updated. The business rule will export the OpenAPI YAML for the API and save it to a file. You can then use this file to include your ServiceNow APIs in a dictionary with other non-ServiceNow APIs for engineers to find when searching.

Give a thumbsup if this works for you!

Akshay Gupta

[sophiya-singh]

Hi Akshay, I tried out this code, but I am getting this error: 

"sn_rest_api_explorer" is not defined.

Any suggestions how to fix this issue?  

[Chris Yang]

This seems like a chatGPT response, it often makes up fictitious API in its responses based on my experience.

I'm also interested in topic as I recently had to manually write some yaml files for documentation, so being able to export would be a good time saver.

Update:

Found it, you can export by going to Rest API Explorer -> at the bottom, there is a link to "Export OpenAPI Specification (YAML)". It's a good start, but you still need to populate the response