From e4b4cc770349a2e25c1224be19cbd33bb10588c4 Mon Sep 17 00:00:00 2001 From: Arlina Espinoza Date: Wed, 6 May 2020 01:47:19 -0700 Subject: [PATCH] [#71] Apidoc - README. --- README.md | 58 +++++++++++++++++++++++++++++++++++++++++++------------ 1 file changed, 46 insertions(+), 12 deletions(-) diff --git a/README.md b/README.md index 4e23db5..734ab80 100644 --- a/README.md +++ b/README.md @@ -4,13 +4,11 @@ Render OpenAPI specs as documentation to your API developers. ## Overview -When you enable this module, it creates a new Drupal entity in your system named +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. Make sure to change the -"View published API docs" permissions if you want to allow registered or anonymous users -to be able to view published API documentation. +"APIs" menu item on the site using a Drupal view. The OpenAPI spec by default is rendered using Apigee's SmartDocs custom field formatter. @@ -26,27 +24,63 @@ To render the OpenAPI spec using Swagger UI: 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 entity, you can configure it at __Structure > API docs__ in the admin +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) +This API Doc is a node type, so any node access control module from contrib will work to restrict access and play well +with views. To set up an RBAC, we recommend ["Permissions by term"](https://www.drupal.org/project/permissions_by_term), +which can cover the following scenarios: + +- Restrict access on reading docs or creating apps: +As an API Provider, I only want certain developers or teams of developers to read documentation or use a given +API product so that I can hide that API Product from most developers. +To implement using "Permissions by term": +1. Create roles that match the API Product RBAC, and assign users accordingly. +2. Create a new term for each of the roles. +3. On the API Doc node, tag it with the desired term. + +- Restrict access to creating apps +As an API Provider, I want any developer or teams of developers to be able to read documentation about a given +API product, but want to only allow certain developers to be able to use that API product so that we can add manual or +automatic steps before approving access. +To implement using "Permissions by term": +1. Create a role for each teams of developers, and assign users accordingly. (The important step here is that the +API Product RBAC does not need to match the API Doc's.) +2. Create a new term and allow above the role(s) on it. +3. On the API Doc node, tag it with the above term. + +- Set access defaults for new API Products +As an API provider, I want to set the access control of a new API Product to be hidden for all users except +certain people on my team so that developers do not use the product until I have tested it. +To implement using "Permissions by term": +1. Create a role for your team, and assign users accordingly. +2. Create a new term and allow above the role on it. +3. On the API Doc node, tag it with the above term. + +Note: The instructions outlined above will only control access to the API Doc, not to the API product. + ## Planned Features -- Integration with Apigee API Products +- Integration with Apigee API Products. - Add visual notifications when source URL specs have changed on the API Doc admin screen ### Known issues +- No backwards compatibility with the version 1.x of this module. Follow this issue for updates: +https://github.com/apigee/apigee-api-catalog-drupal/issues/80 + - 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 nodes or other entities. + 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](https://www.drupal.org/docs/develop/using-composer/using-composer-to-manage-drupal-site-dependencies) +[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/). @@ -57,7 +91,7 @@ to get you started quickly. cd /path/to/drupal/root composer require drupal/apigee_api_catalog ``` - For more information about installing contributed modules using Composer, read + For more information about installing contributed modules using Composer, read [how to download contributed modules and themes using Composer](https://www.drupal.org/docs/develop/using-composer/using-composer-to-manage-drupal-site-dependencies#managing-contributed). 2. Choose **Extend** in the Drupal administration menu. 3. Select the **Apigee API catalog** module. @@ -65,8 +99,8 @@ to get you started quickly. ## Development -Development is happening in our [GitHub repository](https://github.com/apigee/apigee-api-catalog-drupal). The Drupal.org issue -queue is disabled; we use the [Github issue queue](https://github.com/apigee/apigee-api-catalog-drupal) to coordinate +Development is happening in our [GitHub repository](https://github.com/apigee/apigee-api-catalog-drupal). The Drupal.org issue +queue is disabled; we use the [Github issue queue](https://github.com/apigee/apigee-api-catalog-drupal) to coordinate development. See [CONTRIBUTING.md] for more information on contributing through development. ## Support