SmartDocs and Swagger UI - A Comparison

7 11 4,617

Hello everyone,

I was recently asked to put together a comparison of the features SmartDocs and Swagger UI offers out-of-the-box for the Drupal-based developer portal. I thought I'd share that information here for the community to share and improve. Feel free to leave comments if I'm mistaken about any of the features. Thanks!

SmartDocs

SmartDocs is the current API documentation solution offered in the Drupal 7-based developer portal (not the out of the box portal integrated directly into Apigee Edge). SmartDocs allows developers to read about APIs, send a live request and view a live response from the API. SmartDocs can import and render OpenAPI 2.0 specifications as HTML documentation for consumers.

https://docs.apigee.com/api-platform/publish/drupal/using-smartdocs-document-apis

Swagger UI Field Formatter

Swagger UI Formatter leverages the Swagger UI project to render API documentation in developer portals. Similar to SmartDocs, developers are able to read about APIs, send live requests and view responses from the API. Swagger UI Formatter is compatible with OpenAPI 2.0 specifications with support for 3.0 as well.

Library link:

https://github.com/swagger-api/swagger-ui

Developer Portal module link:

https://www.drupal.org/project/swagger_ui_formatter

Feature SmartDocs Swagger UI
Layout Multiple pages per model. One page per resource. One page per model. All resources are listed on a single page, rendered dynamically.
Supported versions of the OpenAPI Spec (fka Swagger) 1.2, 2.0
2.0, 3.0 (with the 7.x-2.x-dev module)
Live Testing Available, does not require CORS to be enabled. Available*

* Requires additional CORS headers consideration. Configure all your Edge proxies to respond with CORS headers, or use the public edge send request proxy. See the comment below.
Drupal 8
(in alpha)
Not available today Already available as a module in Drupal 8
Response Model Schema Not available without significant customization and the SmartDocs Extend module. Available
Search Individual resource pages indexed alongside other content with access controls. Not optimized
Access Controls Can be applied to individual resources' pages Applicable only to the single page rendered from the spec
Original Spec Publishing Can be enabled with the SmartDocs Extend module. Stored as a file in the developer portal
SEO One page per resource improves SEO results for external facing developer portals. One page per model; has significantly lower SEO than SmartDocs.
Theming Deep customization of layout, theme, and behavior through templating tools (requires non-trivial effort). Limited to CSS changes, such as color schemes

In addition to the above, please see @Anil Sagar's great article about what can be improved in SmartDocs.

[edited for accuracy]

Comments
johnbanning
Participant I

This is helpful. Thank you for compiling.

chrisnovak
Staff

I would put an asterisk on the "OpenAPI Spec Support" section for SmartDocs since it does not fully support all features of OpenAPI 1.2 & 2.0.

karlscheirer
Participant V

Another suggestion: live testing with swagger ui requires a little extra work to get proper CORS responses - either configure all your edge proxies to respond with cors headers, or use the public edge sendrequest proxy.

Smartdocs automatically uses the edge sendrequest proxy (https://apiconsole-prod.apigee.net/smartdocs/v1/sendrequest) for you.

anilsr
Staff

Great Article @kengilbert +1 !!!

chrisnovak
Staff

@kengilbert for the "TBD" in the roadmap column for SmartDocs, you can change it to note that it is not currently available in Drupal 8. Thanks for putting this info together.

kengilbert-1
Participant II

Done. Thanks Chris!

Marsh
Staff

By comparison, Swagger UI renders more detail from the spec than SmartDocs does; however, that was something of a design choice.

Marsh
Staff

Ken, thanks for this comprehensive writeup. Because this could turn out to be a referenced article, I've taken a direct edit pass to correct some sections and/or to make them more precise--I hope you don't mind! I've saved a copy of your text before that edit, if you need it, it should be in the edit history.

kengilbert-1
Participant II

Thanks Marsh! No problem at all. That makes perfect sense to me.

patti
New Member

Hi Karl - The response that the public edge sendrequest proxy returns is not the targeturl response. From what I can tell, it returns the targeturl response plus some extra data. So, when I tried it in a Swagger UI, the CORS handling worked, but the response displayed has the additional sendrequest proxy response data. Did you find a way around this in a Swagger UI so that only the targeturl response is displayed?

shshankmathur
Participant II

Another difference would be the support provided by Google with SmartDocs and the lack of it with swagger-ui.

I wonder if there is any module which provides APIs for swagger-ui like the 'smartdocs-service' module.

Version history
Last update:
‎07-25-2018 10:57 AM
Updated by: