SmartDocs - A custom module to your rescue - Fix for SmartDocs issues

[anilsr]

Hello Everyone,

In my last article related to smartdocs, We have discussed about multiple issues related to SmartDocs & how it fails to address basic things.

In this article, we are going to see solutions to some of the issues & how they are addressed. I will be updating this article moving forward to fix critical things related to SmartDocs. Feel free to share your feedback using comments.

Fix SmartDocs issue using below custom extension module,

smartdocs_extend :

• What is it ?
  • A Drupal Custom Module to fix SmartDocs issues.
• Installation Instructions ?
  • Find here in github : https://github.com/anil614sagar/smartdocs_extend/
• Support ?
  • Community support only
• Anything else ?
  • Apigee DO NOT support this module officially. Feel free to leverage Apigee Community to provide feedback & pull request in github for any changes.

Version : 7.x-1.0 :

Issue 1 : Original Spec Lost

Solution:

• Spec is stored locally in database when you upload same & Available in SmartDocs revision details page to download.
• How it's implemented ?
  • A simple install hook in .install file that creates the table schema.
  • hook_smartdocs_model_import in .module file to hook into import process, push the spec into database
  • hook_menu in .module file to create a downloadable path
  • hook_form_id_alter .module file to embed download link in SmartDocs model revision details page.

Issue 2 : Limited data available in handlebar variables in the template

Solution:

• Retrieve the locally stored spec from database.
• Embed raw spec & spec definitions as javascript json variable "api_raw_spec" using hook_node_view
• Supports only Open API Spec JSON format as of today.
• You can pull the raw spec in SmartDocs template javascript using "api_raw_spec" variable & modify the template code to display additional information.

Issue 3 : Request Body Sample is incomplete - Fails to render properly if spec contain parameters which are objects / arrays inside object

Solution :

• Fixed the bug in request sample generator code present in model.js. Updated the model.js & replaced the core model.js with updated one using hook_js_alter in module file. You can see model.js inside js folder.

Issue 4 : Default values missing in sample request body sample

Solution :

• Fixed the bug in request sample generator code present in model.js. Updated the model.js & replaced the core model.js with updated one using hook_js_alter in module file. You can see model.js inside js folder.
• Just installing above module will take care of fixes.
• Thanks to @yuriyl for the original fix mentioned in the article here. Few modifications are done to support both example & default.
• Specify the default values using "example" or "default" key in OpenAPI Spec parameter definition.

More fixes are coming soon. Stay tuned & Leave your feedback !

Hope it's helpful. Feel free to provide feedback of the above module using comments below.

-------------------------------

Anil Sagar

Learn Apigee Concepts in 4 Minutes - HandsOn

[anilsr]

@mark.ferguson FYI.. You might be interested in above solution.

[jackpetraitis]

Thanks for doing this. I have a question... where are smartdocs.hbr copies stored? For example, when you create a new model it copies your method template. Where is that template copy stored?

[anilsr]

@Jack Petraitis , You can upload default smartdocs copy in Configuration > SmartDocs in Developer Portal. Navigate using black color admin menu on top of screen. Hope it helps.

[#5]

@Anil Sagar I saw that module contains model.js file and you customized it to add new features. What will it happen when we upgrade to a new release? Will these new features be included in the new release? Or will you publish new compatible version of the module? Thanks for your help.

[anilsr]

@donghyunlee , Welcome to Apigee Community.

I am trying my best to have these features in the new release. If not, Will publish new compatible version of the module.

Hope it helps.

[daniel_biales]

Hi, has anyone tried using this in conjunction with the smartdocs service module. I tried and have had issues. https://github.com/anil614sagar/smartdocs_extend/issues/3

[gluskin-samuel]

@Anil Sagar, would you recommend downloading your version of the module or the fork by achieve-internet which is 7 commits ahead of you? Any reason why you have not merged those commits?

[gluskin-samuel]

@Anil Sagar When I click "Download Original Spec" it downloads a blank file titled "1". I thought the problem might be that one has to import the spec after smartdocs_extend has been installed. So I deleted the model and then imported it again after the module was installed. But the file is still blank when clicking "Download Original Spec." Thanks for all your work on this.

[anilsr]

@Shai Gluskin , I have merged the commits.

[gluskin-samuel]

@Anil SagarThanks so much. After I updated the smartdocs_extend module with the latest version with the commits that you merged I was able to see that a json version of the spec is now stored in the database and I could download it using the "Download Original Spec" button. Of course, any spec that I want to be available in this way, I need to delete and re-import it

[gluskin-samuel]

@Anil Sagar @ GoogleI'm getting "TypeError: obj is undefined" referencing two parts of the template's js:

1. if (obj.hasOwnProperty('properties')) {
                   for (k in obj['properties']) {
                       obj['properties'][k].name = k;
                       reqResParams.push(obj['properties'][k]);
                       if (obj['properties'][k].hasOwnProperty('properties')){
                           extractParametersInfo( obj['properties'][k], reqResParams);
                       }
   	

and

2. extractParametersInfo(requestParamsSchema, reqResParams);
   	

In the page source I can see the definitions data I want to display on the page in the source code. It follows

Apigee.APIModel.expandedSchema={"profit_centers":{ <br> I need help getting that data to print from the template. I used the handlebars {{api_raw_spec}} but didn't succeed.

[ahmedeiddev]

Hi @Anil Sagar
I'm new in Apigee,
I am trying to show sample request payload if request contains object within an object with out $ref reference, so I was looking at the solution suggested by you, I saw smartdocs_extend module contains model.js but not able to get the sample on request payload. Kindly suggest me.

[joanjames]

Have these fixes been merged into the latest version of Smartdocs? We are running Smartdocs Version 7.x-5.9 and the Smartdocs Extension.

We are still not seeing the Request Body sample. (Issue 3) However, the schema displays in the edit view of the method. If a $ref is used, the $ref displays in the edit view but not the expanded schema.