Developers Corner

SmartDocs and Swagger UI - A Comparison

Sep. 26 2018
Ken Gilbert
Lead Engineer

Below is a comparison of the features SmartDocs and Swagger UI offers out-of-the-box for the Drupal-based developer portal. The information here is to highlight the difference between two commonly used modules and to make it clear what could work best for your business. 

 

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 Set Comparison

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

 

More about Developers Corner

  Welcome Drupal 8.6! More change to the Drupal-verse landscape, and more new features to look forward to. This will obviously affect all current D8 users, but what should you look out for? Let's examine how it might impact your site and what unexpected issues may occur.   
Below are some of the key technical components that are required for a sound SEO strategy presented by our Director of Technical Services, Christoph Weber. Christoph has deep technical SEO experience and has vast proven experience within the field.