SmartDocs - Alternative to Swagger UI - Great Features - Missing Basics - What works - What doesn't work

[anilsr]

Hello Everyone,

SmartDocs is absolutely differentiator & awesome feature in developer portal. But, It fails when it comes to basic things.

Let me start with pain points of Smartdocs.

• Open API Specification is lost once you import same to generate Smartdocs !!
  • We never stored OpenAPI Spec in Developer Portal. It's sent to Apigee API Model Datastore & Converted into smartdocs json with subset of information present in Original Spec.
  • What can be done ? : Store spec locally & give it back to Portal Administrator.
  • Solution : Find out how to fix same here.
• Limited data available in handlebar variables in the template
  • While generating the smartdocs JSON, only subset of information is taken & rest is lost into thin air.
  • What can be done ? : Store spec locally & make it available for the template
  • Solution : Find out how to fix same here.
• Request Body Sample is incomplete - If has any objects or arrays
  • It's a bug. It fails to generate sample request payload if request contains object within an object with out $ref reference.
  • What can be done ? : Fix the bug in model.js . It should be few lines fix.
  • Solution : Find out how to fix same here.
• Default values missing in sample request body sample
  • It's a bug.
  • What can be done ? : Fix the bug in model.js . It should be few lines fix.
  • Solution : Find out how to fix same here.
• Sample Response Schemas & Sample Response Payload missing
  • While generating the smartdocs JSON, only subset of information is taken & rest is lost into thin air.
  • What can be done ? : Store spec locally & make it available for the template.
• List of request parameters in a table format
  • I would like to see a table with request payload parameters like name, datatype, required or not, description etc in the method page.
  • What can be done ? : Modify template to have this feature. It should be few lines fix.
• Where are error codes ?
  • Error codes of response are present in spec but nowhere seen in smartdocs. It's again due to same reason while generating the smartdocs JSON, only subset of information is taken & rest is lost into thin air.
  • What can be done ? : Store spec locally & make it available for the template. Modify template to display this information.
• Where are error responses ?
  • Error responses are present in spec but nowhere seen in smartdocs. It's again due to same reason while generating the smartdocs JSON, only subset of information is taken & rest is lost into thin air.
  • What can be done ? : Store spec locally & make it available for the template. Modify template to display this information.
• Support for custom metadata / Display addition information in smartdoc pages ?
  • Open API spec supports custom extenstions using x-{somename}. It's again due to same reason while generating the smartdocs JSON, only subset of information is taken & rest is lost into thin air.
  • What can be done ? : Store spec locally & make it available for the template. Modify template to display this information.
• It's not like Swagger UI ?
  • Smartdocs is actually lot flexible than Swagger UI when it comes to categorizing content, search, RBAC, template, themeing etc. But, Due to the reason basic information is lost while importing, Smartdocs feels subpar when it comes to amount of information displayed in the UI.
  • What can be done ? : Store spec locally & make it available for the template. Modify template to display information similar to swagger UI.
• Mapping between API Products & API Documentation ?
  • No relation to API Products & Smartdocs models confuses developers which API is part of API product.
  • What can be done ? : Name your Model similar to API Product or Have a page which explains mapping between API Products & SmartDocs API Documentation.
• Required vs Optional Parameters in request payload ?
  • I would like to see a table with request payload parameters like name, datatype, required or not, description etc in the method page.
  • What can be done ? : Modify template to have this feature. It should be few lines fix.
• Where is production URL ?
  • By default, SmartDocs is pointed to sandbox environment API Endpoints. How can i display production endpoint ?
  • What can be done ? Modify template to hard code the production URL. Even better, Modify the javascript to switch API HostName based on user choice.
• Smartdocs Template is cluttered !!
  • CSS, JS, HTML all in one place in single text area. It sucks. Can't modify anything.
  • What can be done ? Provide option to manage same in file system inside a custom module or theme.
• Where is XML Support ?
  • What can be done ? Auto generate sample XML request payload from spec.
• Default API Doc pages UX is very basic.
  • Lot of empty spaces, scattered text. It's an eyesore.
  • What can be done ? Modify the template to make it pretty.

SmartDocs - A differentiator :

• Ability to categorize API Documentation leveraging Drupal concepts.
• RBAC - Role based access control
• Search - Search individual API
• Templating - Theme - Look & Feel - Flexibility it provides with custom template.

All in all, Smartdocs is a really cool feature but complex when it comes to customization. Sometimes few has given up on smartdocs & preferred swagger UI. I am working on solving above issues one at at time. Stay tuned to see solutions for above problems.

We would love to hear any other important & critical missing features in smartdocs from community. Please share your feedback using comments below & I am happy to update above list with your feedback to summarize things for others.

Would love to hear your feedback using comments below.

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

Anil Sagar

Learn Apigee Concepts in 4 Minutes - HandsOn

[#2]

Great article @Anil Sagar

I've been looking at Smartdocs myself and have been concerned that OAS information is being lost on import.

I also have concerns about the linkage between smartdocs and API products. As an API consumer I can't see any obvious way to look at a smartdoc and then discover which product(s) that API belongs to. Is there a pattern for this?

[anilsr]

@mark.ferguson , Thank you for your feedback. Appreciate taking your time for same.

Regarding, OAS information is being lost on import.

• I am working on same as we speak. Stay tuned !

Regarding, Linkage between Smartdocs and API products.

• Have same name for API Products & SmartDocs models. It will become easy for developers to identify which API comes under which API Product.
• Have a link in API Doc page with little customization that says, "Subscribe to API" which takes developer to /user/me/app/add page with queryparam ?apiproduct={api-product-name} where in add app screen pre-select API Product by customizing form.
• Have a page in Developer Portal that explains mapping between API Products & API Models if names are different.
• Have a link in Add App Screen next to API Product that points to relevant documentation page as well as in App Details section next to API Product.

Stay tuned with this article.

[#4]

Thanks for answering. We are hopefully going to implement continuous delivery for our API deployments into the gateway and publishing into the portal. Do you know of a way to do this from an automation / data driven approach ? I've seen reference to Smartdocs tags but I can't find much material on how they work. You could in theory tag the model with the products it belongs to prior to importing it. Are tags a structured taxonomy e.g. tags need to exist before they are used or do tags get added to the taxonomy as they appear?

[anilsr]

@mark.ferguson ,

Great idea regarding leveraging tags. I will definitely keep in mind while implementing solution for same. At present tags are used to categorize APIs in developer portal.

Yes, You can leverage them to map to API Product by having same tag name as API Product & build a custom view in Developer Portal quickly. You can do that today with out any custom code by just doing configuration in Developer Portal using views module. Only downside is, You can't use tags for generic categorization.

Tags get added automatically in Developer Portal from OpenAPI Spec.

[#6]

Hi @Anil Sagar, I am trying to show the sample response schema/payload in the api definition, so I was looking at the solution suggested by you, but quite didn't get that, wondering if you can briefly elaborate on that, here is your comment - "What can be done ? : Store spec locally & make it available for the template. Modify template to display this information."

Can you please briefly provide the steps to do that?

Thanks!

[anilsr]

@Naveen Dokuparthi , See article here that explains "Store spec locally & make it available for the template".

Stay tuned for template updates that will display response samples. You can do that too by editing smartdocs template with little bit of javascript.

[franklino]

@Anil Sagar : fantastic write up. will the templates and other improvement you describe be available for OPDK deployments as well?

[anilsr]

@frank lino , Yes, You can go ahead & use above templates, custom modules in OPDK too.

In fact, Cloud & OPDK it's same code & features.

[#10]

Hi @Anil Sagar

I am trying to display response error code headers in smartdocs page but finding that data is not available. Seems Headers information is being lost on import. Is there any way to get the error code headers?

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

[sandeepshinde]

Hi @Anil Sagar @ Google

I am looking for a D8 module is there a proposal for that to be developed or is there any alternative for D8.

[chrisnovak]

Hello @Sandeep Shinde we just released our API Catalog module for Drupal 8 which contains our new version of SmartDocs. Here is a screenshot:

This feature is also part of our Apigee Devportal Kickstart Drupal distribution. Kickstart contains a theme and example data to get you quickly started.