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.
SmartDocs - A differentiator :
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
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?
@mark.ferguson , Thank you for your feedback. Appreciate taking your time for same.
Regarding, OAS information is being lost on import.
Regarding, Linkage between Smartdocs and API products.
Stay tuned with this article.
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?
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.
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!
@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.
@Anil Sagar : fantastic write up. will the templates and other improvement you describe be available for OPDK deployments as well?
@frank lino , Yes, You can go ahead & use above templates, custom modules in OPDK too.
In fact, Cloud & OPDK it's same code & features.
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.
I am looking for a D8 module is there a proposal for that to be developed or is there any alternative for D8.
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.