Dear @José Cedeño ,
Great thoughts and awesome feedback. Please find my opinion on same. I am sure others will have better opinions and look forward to hear.
- Drupal is a robust platform to build and it makes sense to use it as a starting point for the developer portal. There's a lot of modules and a big community behind it.
Yes, Drupal is a powerful CMS and industry proven platform to build Developer Portal experiences. You can do N number of things using Drupal CMS with the power of contributed modules & community. Like Twitter, LinkedIn, EBay developer portals Apigee Developer Portal distribution is also built using Drupal CMS. It's easy to customise experience & introduce new workflows within a short time using powerful Drupal APIs & Custom Modules. It may require Drupal Experience sometimes.
- The smartdocs can only be adding by importing a swagger or wadl file. You cannot edit or add them by hand. Smartdocs basically take your swagger file and create nodes, tags and use taxonomy to build the documentation pages. This approach seems to overcomplicate things. It discourages you from editing the nodes by hand if you're using your swagger file as the source of your docs.
Yes, Agree. Its confusing & not a great experience when you edit nodes whereas source of your smartdocs docs is swagger or wadl. Ideally, We should have capability of swagger editor in built into Developer Portal. We will take it as a feature request.
- The drupal dev portal is tied to the API gateway since it lists your API products and respects their visibility, but the smartdocs are not. You have to specify in the swagger files, what is the url and base path for the api endpoint.
Agree, API Proxies / API Products / Permissions is not tied to SmartDocs & both currently work independently. Ideally, We should have defined once & reuse at multiple places. Like you upload swagger spec - Create API Proxies, Generate SmartDocs, Map Permissions. Hopefully feature versions of smartdocs will have it as a configurable options where we can pull the values from Apigee Edge.
- You can't seem to tie the permissions of the API product to the permissions of the documentation. All the uploaded smartdocs are shown in the /apis generated view page. If you have some private API products, it looks like you have to hide those smartdocs by hand.
Yes, API Products & Smart Docs categories are not mapped. You need to manually do it in developer portal. If you are looking to restricting smartdocs in developer portal, You can restrict visibility based on Drupal Node Permissions using modules like Content Access. Its a temporary work around that we can suggest for now.
- There doesn't seem to be a way to tie the various environments available in the API gateway to the developer portal. For example, the registration page just lists the available products. I can't seem to have a way to allow people to register for just the dev API products.
It can be achieved in Developer Portal by implementing custom modules & workflows. We have implemented same for many customers as part of customisations. Agree, there should be a way to define dev API Products vs Live API Products in developer portal as well as edge. It should be available as out of the box feature in Developer Portal. We will take it as a feature request.
- The try-api feature doesn't automatically populate my developer API key. Maybe there's something that I haven't configured, but I would expect that since the developer portal knows who I am and I have an API key, it would automatically populate them for me in either the header or GET parameter as required by the api endpoint. Instead I have to remember if the API key is in the header or parameter and then copy & paste it.
I believe smart docs provides this default configuration. @sgilson @Gitesh Koli @seshi Any Idea ?
- The forum UI seems to be a bit rustic. I think this is due to the forum module in Drupal.
Yes, It's due to default forum module. You can use Advanced Forum module or customise it to change look & feel. See one of our customer portal forums using Advance Forum & custom css here.
- The register application screen doesn't seem to allow for help or more context information for the API products. For example, it would be nice to provide a link for extra documentation next to the API product so that the developer knows if this is what they need.
Agree, Great Feedback. We will take it as a feature request and let our team know about it.
- When a developer views the smartdoc, there doesn't seem to be a link right there to allow the developer to request access to that given API product.
It can be built as a custom feature. But, there are couple of questions like do you create a new app ? add api product to existing app ? It depends on requirements of customer who is implementing it.
- You may have different API proxies and products to control the permissions of the resources and paths. On the other hand, there's just one smartdoc per swagger file.
You can also upload multiple swagger files & generate multiple smartdocs respectively.
We really appreciate taking your time to share very valuable feedback. It's really helpful for us.
Cheers,
Anil Sagar
LinkedIn
Twitter
