[DRUP-610] Add url as source for apidocs spec file and (DRUP-459) allow re-fetching it afterwards.

README.md

@@ -14,18 +14,28 @@ to be able to view published API documentation.
 
 The OpenAPI spec by default is rendered using Apigee SmartDocs.
 
+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 an enable the [Swagger UI Field Formatter](https://www.drupal.org/project/swagger_ui_formatter) module.
+2. Install the Swagger UI JS library as documented [on the module page](https://www.drupal.org/project/swagger_ui_formatter).
+3. Go to __Configuration > API catalog > Manage display__ in the admin menu.
+4. Change "OpenAPI specification" field format to use the Swagger UI field formatter.
+
 The API Doc is an entity, you can configure it at __Configuration > API catalog__ in the admin
 menu.
 
-The "APIs" menu link is a view, you can modify it by  editing the "API Catalog" view
+The "APIs" menu link is a view, you can modify it by editing the "API Catalog" view
 under Structure > Views in the admin menu.
 
 ## Planned Features
 
 - Integration with Apigee API Products
-- Allow OpenAPI specs to be associated to a source location such as Apigee Edge or a URL
 - Add visual notifications when source URL specs have changed on the API Doc admin screen
-- Ability to update API Docs when source location changes
 
 ### Known issues
 
@@ -35,10 +45,10 @@ under Structure > Views in the admin menu.
 
 ## Installing
 
-This module must be installed on a Drupal site that is managed by Composer.  Drupal.org has documentation on how to
+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](https://www.drupal.org/docs/develop/using-composer/using-composer-to-manage-drupal-site-dependencies) 
 to get you started quickly.
-  
+
 1. Install the module using [Composer](https://getcomposer.org/).
   Composer will download the this module and all its dependencies.
   **Note**: Composer must be executed at the root of your Drupal installation.

apigee_api_catalog.info.yml

@@ -7,4 +7,5 @@ configure: entity.apidoc.settings
 dependencies:
 - drupal:text
 - drupal:file
+- drupal:file_link
 - apigee_edge:apigee_edge

apigee_api_catalog.links.task.yml

@@ -15,8 +15,8 @@ entity.apidoc.edit_form:
   title: 'Edit'
 
 entity.apidoc.delete_form:
-  route_name:  entity.apidoc.delete_form
-  base_route:  entity.apidoc.canonical
+  route_name: entity.apidoc.delete_form
+  base_route: entity.apidoc.canonical
   title: 'Delete'
   weight: 10
 
@@ -25,3 +25,15 @@ apidoc.admin:
   route_name: entity.apidoc.collection
   base_route: system.admin_content
   weight: 10
+
+entity.apidoc.version_history:
+  route_name:  entity.apidoc.version_history
+  base_route:  entity.apidoc.canonical
+  title: 'Revisions'
+  weight: 15
+
+entity.apidoc.reimport_spec_form:
+  route_name: entity.apidoc.reimport_spec_form
+  base_route: entity.apidoc.canonical
+  title: 'Re-import OpenAPI spec'
+  weight: 15

apigee_api_catalog.module

@@ -40,4 +40,3 @@ function apigee_api_catalog_help($route_name, RouteMatchInterface $route_match)
     default:
   }
 }
-

apigee_api_catalog.permissions.yml

@@ -17,3 +17,11 @@ view published apidoc entities:
 
 view unpublished apidoc entities:
   title: 'View unpublished API docs'
+
+view apidoc revisions:
+  title: 'View API Doc revisions'
+  description: 'To view a revision, you also need permission to view the item.'
+
+revert apidoc revisions:
+  title: 'Revert API Doc revisions'
+  description: 'To revert a revision, you also need permission to edit the item.'

apigee_api_catalog.services.yml

@@ -1,4 +1,9 @@
 services:
+
   logger.channel.apigee_api_catalog:
     parent: logger.channel_base
     arguments: ['apigee_api_catalog']
+
+  apigee_api_catalog.spec_fetcher:
+    class: Drupal\apigee_api_catalog\SpecFetcher
+    arguments: ['@file_system', '@http_client', '@entity_type.manager', '@string_translation', '@messenger', '@logger.channel.apigee_api_catalog']

composer.json

@@ -5,7 +5,8 @@
     "description": "Apigee API Catalog for Drupal",
     "require": {
         "php": ">=7.1",
-        "drupal/apigee_edge": "~1.0-rc4"
+        "drupal/apigee_edge": "~1.0-rc4",
+        "drupal/file_link": "~1.0"
     },
     "require-dev": {
         "drupal/coder": "^8.3",

src/Entity/Access/ApiDocAccessControlHandler.php

@@ -20,43 +20,131 @@
 
 namespace Drupal\apigee_api_catalog\Entity\Access;
 
+use Drupal\apigee_api_catalog\Entity\ApiDocInterface;
 use Drupal\Core\Entity\EntityAccessControlHandler;
+use Drupal\Core\Entity\EntityHandlerInterface;
 use Drupal\Core\Entity\EntityInterface;
+use Drupal\Core\Entity\EntityTypeInterface;
+use Drupal\Core\Entity\EntityTypeManagerInterface;
 use Drupal\Core\Session\AccountInterface;
 use Drupal\Core\Access\AccessResult;
+use Symfony\Component\DependencyInjection\ContainerInterface;
 
 /**
  * Access controller for the API Doc entity.
  *
  * @see \Drupal\apigee_api_catalog\Entity\ApiDoc.
  */
-class ApiDocAccessControlHandler extends EntityAccessControlHandler {
+class ApiDocAccessControlHandler extends EntityAccessControlHandler implements EntityHandlerInterface {
+
+  /**
+   * The entity type manager.
+   *
+   * @var \Drupal\Core\Entity\EntityTypeManagerInterface
+   */
+  protected $entityTypeManager;
+
+  /**
+   * Constructs an access control handler instance.
+   *
+   * @param \Drupal\Core\Entity\EntityTypeInterface $entity_type
+   *   The entity type definition.
+   * @param \Drupal\Core\Entity\EntityTypeManagerInterface $entityTypeManager
+   *   The entity type manager.
+   */
+  public function __construct(EntityTypeInterface $entity_type, EntityTypeManagerInterface $entityTypeManager) {
+    parent::__construct($entity_type);
+    $this->entityTypeManager = $entityTypeManager;
+  }
+
+  /**
+   * {@inheritdoc}
+   */
+  public static function createInstance(ContainerInterface $container, EntityTypeInterface $entity_type) {
+    return new static(
+      $entity_type,
+      $container->get('entity_type.manager')
+    );
+  }
 
   /**
    * {@inheritdoc}
    */
   protected function checkAccess(EntityInterface $entity, $operation, AccountInterface $account) {
-    $parent_access = parent::checkAccess($entity, $operation, $account);
-
-    if (!$parent_access->isAllowed()) {
-      /** @var \Drupal\apigee_api_catalog\Entity\ApiDocInterface $entity */
-      switch ($operation) {
-        case 'view':
-          if (!$entity->isPublished()) {
-            return $parent_access->orIf(AccessResult::allowedIfHasPermission($account, 'view unpublished apidoc entities'));
-          }
-          return $parent_access->orIf(AccessResult::allowedIfHasPermission($account, 'view published apidoc entities'));
-
-        case 'update':
-          return $parent_access->orIf(AccessResult::allowedIfHasPermission($account, 'edit apidoc entities'));
-
-        case 'delete':
-          return $parent_access->orIf(AccessResult::allowedIfHasPermission($account, 'delete apidoc entities'));
-      }
+    /** @var \Drupal\apigee_api_catalog\Entity\ApiDocInterface $entity */
+    $access = parent::checkAccess($entity, $operation, $account);
+
+    // Access control for revisions.
+    if (!$entity->isDefaultRevision()) {
+      return $this->checkAccessRevisions($entity, $operation, $account);
+    }
+
+    switch ($operation) {
+      case 'view':
+        return $access->orIf($entity->isPublished()
+          ? AccessResult::allowedIfHasPermission($account, 'view published apidoc entities')
+          : AccessResult::allowedIfHasPermission($account, 'view unpublished apidoc entities')
+        );
+
+      case 'reimport':
+        return AccessResult::allowedIf($entity->spec_file_source->value === ApiDocInterface::SPEC_AS_URL)
+          ->andIf($entity->access('update', $account, TRUE));
+
+      case 'update':
+        return $access->orIf(AccessResult::allowedIfHasPermission($account, 'edit apidoc entities'));
+
+      case 'delete':
+        return $access->orIf(AccessResult::allowedIfHasPermission($account, 'delete apidoc entities'));
     }
 
     // Unknown operation, no opinion.
-    return $parent_access;
+    return $access;
+  }
+
+  /**
+   * Additional access control for revisions.
+   *
+   * @param \Drupal\Core\Entity\EntityInterface $entity
+   *   The entity for which to check access.
+   * @param string $operation
+   *   The entity operation.
+   * @param \Drupal\Core\Session\AccountInterface $account
+   *   The user for which to check access.
+   *
+   * @return \Drupal\Core\Access\AccessResultInterface
+   *   The access result.
+   */
+  protected function checkAccessRevisions(EntityInterface $entity, $operation, AccountInterface $account) {
+    /** @var \Drupal\Core\Entity\EntityStorageInterface $entity_storage */
+    $entity_storage = $this->entityTypeManager->getStorage($this->entityTypeId);
+
+    // Must have access to the same operation on the default revision.
+    $default_revision = $entity_storage->load($entity->id());
+    $has_default_entity_rev_access = $default_revision->access($operation, $account);
+    if (!$has_default_entity_rev_access) {
+      return AccessResult::forbidden();
+    }
+
+    $map = [
+      'view' => "view apidoc revisions",
+      'update' => "revert apidoc revisions",
+    ];
+
+    if (!$entity || !isset($map[$operation])) {
+      // If there was no entity to check against, or the $op was not one of the
+      // supported ones, we return access denied.
+      return AccessResult::forbidden();
+    }
+
+    $admin_permission = $this->entityType->getAdminPermission();
+
+    // Perform basic permission checks first.
+    if ($account->hasPermission($map[$operation]) ||
+      ($admin_permission && $account->hasPermission($admin_permission))) {
+      return AccessResult::allowed();
+    }
+
+    return AccessResult::forbidden();
   }
 
   /**