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 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.
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.
Developer Portal module link:
Feature Set Comparison
|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.
|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