Hello Everyone,
SmartDocs is one of the differentiating factors when it comes to API Documentation in Apigee Edge. It gives you many features out of the box including Search, RBAC, Templating, Customization etc.
I would like to take this opportunity to share with the community how you can improve the User Experience of the SmartDocs landing page from a simple list of API Models to much more visible API Catalog with search & filter capabilities using out of the box configuration & a little bit of css customization.
In this article, You are going to see how to change the SmartDocs landing page in detail.
What do you see when you navigate to /apis page in out of the box Developer Portal ? You will see the list with couple of SmartDocs API models out of the box. More or less similar to below screenshot.
Let's see how to categorize above API Models, Improve Visual & User Experience of above page step by step.
Prerequisites :
Developer Portal Code Base Access. If you have an Apigee-hosted devportal, you need pantheon access. If you are hosting your own devportal, you should have codebase access to the portal.
Step 1 :
Install Drupal contributed module better_exposed_filters in sites/all/modules/contrib folder.
If you are using drush, run the commands below, inside developer portal source code.
drush dl better_exposed_filters-7.x-3.4 drush en better_exposed_filters
If you are not sure how to use drush,
Step 2 :
Let's create some test API models. Let's take a scenario of Banking UseCase & create the API Models & See how it works. Let's create following API Models.
I am sure, There might be many more. Having these many API Models sometimes need categorization & ability to filter the API Catalog.
Let's delete the default hello & pet store API Models & Add above API models using some random OpenAPI Spec.
Step 3 :
Add ability to categorize, API models by leveraging out of the box taxonomy concepts in Developer Portal.
Step 4 :
Reference the above vocabulary in SmartDocs Models vocabulary as a new field.
Let's add one more field called Model Image, which will be used to upload a pic that will get displayed in the SmartDocs APIs landing page.
Step 5 :
Update the SmartDocs API Models with categories & an image.
Step 5 :
Create an image style to auto resize uploaded images.
Step 6 :
Add some custom css to theme the view.
.view-smartdocs-models .view-filters { float: left; width: 170px; min-height: 750px; } .view-smartdocs-models .form-control { border: none; box-shadow: none; } .form-type-bef-checkbox { clear: both; } .form-type-bef-checkbox input { float: left; width: 15px; } .form-type-bef-checkbox label { float: left; margin-top: 11px; margin-left: 15px; } .view-smartdocs-models ul { list-style: none; } .view-smartdocs-models ul li { float: left; width: 230px; padding: 10px; border-bottom: 6px solid #c8c9c7; box-shadow: 0 0 3px 0 rgba(0,0,0,.35); margin-top: 10px; margin-left: 10px; min-height: 150px; cursor: pointer; } .view-smartdocs-models .views-field.views-field-name { margin-top: 15px; text-align: center; } .view-smartdocs-models .bef-checkboxes label { color: #666; font-size: 13px; font-weight: normal; } .view-smartdocs-models label[for=edit-field-model-category-tid] { font-size: 16px; } .view-smartdocs-models .views-field-field-model-image-fa-icon { text-align:center; margin-top:20px; }
stylesheets[all][] = css/apicatalog.css
Step 7 :
We are almost there, It's time to update the view. Navigate to APIs (/apis) page as Administrator.
Some reference links in Developer Portal to work with content,
Hope it's helpful. Any feedback / suggestions / Queries ? Please use comments below.
Sweet, Anil!
Hey, here's a tip I used recently. I wanted to allow a "all/none" checkbox or button in the categories list. And I wanted to remove the "Reset" button. Like this:
I found that BEF allows us to remove the reset and add the "all / none". Do that in the UI, under advanced settings like this:
And then add this to the .CSS:
/* ================================================================== */ /* style the anchor inserted by BEF like a bootstrap button */ .bef-select-all-none > a.bef-toggle { background-color: #009FD0; background-image: -moz-linear-gradient(center top , #00A4D7, #0197C6); background-repeat: repeat-x; border-color: rgba(0, 0, 0, 0.1) rgba(0, 0, 0, 0.1) rgba(0, 0, 0, 0.25); border-radius: 4px; box-shadow: 0 0 0 0 rgba(0, 0, 0, 0) inset, 0 0 5px 0 rgba(255, 255, 255, 0.3); color: #FFFFFF; cursor: pointer; display: inline-block; font-size: 13px; font-weight: normal; line-height: 24px; margin-bottom: 0; padding: 4px 10px; text-align: center; vertical-align: middle; } .bef-select-all-none > a.bef-toggle:active { background-color: #0197C6; /* 1 151 198 */ } /* ================================================================== */
Awesome @Dino , + 1, Power of Drupal Modules 🙂
How would you include the taxonomy term inside the Smart Doc so it automatically selected the term for you?
In other words so you did not have to come back and edit the published rendered node manually w the term of your choice.
@James Chandler , Welcome to Apigee Community !
Rendered Node ( SmartDocs API Page) is automatically connected to Smartdocs Model Taxonomy. It happens automatically when you create a Smartdoc model & upload your spec.
We just manually map the Smartdoc Models to one more high level category called Smartdoc Model Categories to group Smartdoc Models ( Think Smartdocs Models as API Products which lists APIs part of it).
Thanks Anil!
One question though, the way it automatically went to 'loans' for example. Was that because of the title we gave it? Confused because we used the same Swagger JSON every time.
Say I did want to add a new taxonomy with for example US State and I followed the same instructions and AM also using everything in this tutorial. How would I put the 'US State' tag inside the swagger doc for drupal to automatically map it to the state?