Skip to content

Latest commit

 

History

History
82 lines (58 loc) · 3.9 KB

README.md

File metadata and controls

82 lines (58 loc) · 3.9 KB
Raw

Apigee API Catalog for Drupal

Render OpenAPI specs as documentation to your API developers.

Overview

When you enable this module, it creates a new content type named "API Doc". You can add new API docs under Content > API catalog in the admin menu.

Once added, the API name and description for each API Doc will be displayed in the "APIs" menu item on the site using a Drupal view.

The OpenAPI spec by default is rendered using Apigee's SmartDocs custom field formatter.

The OpenAPI spec can be directly uploaded as a file, or associated to a source location such as Apigee Edge or a URL. A "Re-import OpenAPI spec" operation is available per API Doc to re-import the spec file when source location changes.

The OpenAPI spec by default is shown on the API Doc detail page by default. To render the OpenAPI spec using Swagger UI:

  1. Install and enable the Swagger UI Field Formatter module.
  2. Install the Swagger UI JS library as documented on the module page.
  3. Go to Configuration > API docs > Manage display in the admin menu.
  4. Change "OpenAPI specification" field format to use the Swagger UI field formatter.

The API Doc is an node type, you can configure it at Structure > Content types > API Doc in the admin menu.

The "/apis" page ("APIs" menu link) is a view. You can modify it by editing the "API Catalog" view under Structure > Views in the admin menu.

API Docs RBAC (Role based access control)

API Docs are a node type, so any node access control module from contrib will work to restrict access and play well with views.

To set up RBAC, we recommend "Permissions by term", which can cover the most frequent scenarios. Refer to the online documentation (to be updated as part of #81) for a "How to" guide on setting up the RBAC: https://www.drupal.org/node/3058344

Planned Features

  • Integration with Apigee API Products.
  • Add visual notifications when source URL specs have changed on the API Doc admin screen

Known issues

  • The Apigee SmartDocs formatter can only render one OpenAPI spec per page and the URL pattern must match /api/{entityId}. This means that the formatter will probably not work correctly if you modify the default API Docs view or try to use this file Formatter on other node types or entities.

Installing

This module must be installed on a Drupal site that is managed by Composer. Drupal.org has documentation on how to use Composer to manage Drupal site dependencies to get you started quickly.

  1. Install the module using Composer. Composer will download the this module and all its dependencies. Note: Composer must be executed at the root of your Drupal installation. For example: 
    cd /path/to/drupal/root
composer require drupal/apigee_api_catalog
    For more information about installing contributed modules using Composer, read how to download contributed modules and themes using Composer.
  2. Choose Extend in the Drupal administration menu.
  3. Select the Apigee API catalog module.
  4. Choose Install.

Development

Development is happening in our GitHub repository. The Drupal.org issue queue is disabled; we use the Github issue queue to coordinate development. See [CONTRIBUTING.md] for more information on contributing through development.

Support

This project, which integrates Drupal 8 with Apigee Edge, is supported by Google.