Send Docs Feedback

Using SmartDocs to document APIs

SmartDocs lets you document your APIs on the Developer Services portal in a way that makes the API documentation fully interactive. Interactive documentation means portal users can:

  • Read about your APIs
  • Send a live request to your API
  • View a live response returned from the API

By creating an interactive documentation on your APIs, you make it easy for portal user to learn, test, and evaluate your APIs.

The Edge management API is a RESTful API that enables you to access API Services using any HTTP client. Apigee uses SmartDocs to create interactive documentation for the Edge management API. See that API documentation here.

SmartDocs portal example

To use SmartDocs, you must have an Apigee Developer Services portal. For more information, see Creating a developer portal.

When you first access the portal, you see an example SmartDocs API on the portal Home page called Get Weather for WOEID:

This API uses the Yahoo Weather API to return XML-formatted weather reports based on an identifier called a WOEID (Where On Earth ID). For example, the WOEID for Palo Alto, CA is 12797282:

  1. Click on Get Weather for WOEID to open the API in SmartDocs. The SmartDocs page appears:
  2. Enter the WOEID in the value of the 'w' query parameter. For example, the WOEID of Palo Alto, CA is 12797282.
  3. Select the Send this request button to submit your request.
  4. Select the Request tab to view the request.
  5. Select the Response tab to view the response from Yahoo. 

The Get Weather for WOEID API was created from this WADL file. Download and edit this WADL file, and then use the following procedures to add your own APIs to SmartDocs. See WADL Reference for more on creating WADL files.

How to document your APIs by using SmartDocs

SmartDocs represents your APIs by using a model, where the model contains all the information about your APIs. The portal extracts information about your APIs from the model to render the documentation pages on the portal as Drupal nodes, where each Drupal node corresponds to a page of documentation on the portal.

The general steps that you follow to use SmartDocs are:

  1. Configure the Drupal SmartDocs module on the portal.
  2. Create a SmartDocs model.
  3. Add APIs to the model from a WADL file, Swagger definition, or manually.
  4. Render the model as a collection of Drupal nodes. Each Drupal node contains information about a single API. For example, if a resource in your API supports both a POST and a PUT request, SmartDocs creates a separate Drupal node for the POST and PUT.
  5. Publish the Drupal nodes. Once published, your portal users can view and interact with your API.
  6. Edit the Drupal nodes, either before or after you publish them. You can edit the Drupal nodes by using the Drupal editor or by editing the original WADL file or Swagger definition. When you are done editing the WADL file or Swagger definition, import it back into the model as a new revision, then render and publish your changes.
  7. Enable SSL. Because SmartDocs can send authentication credentials to your backend as part of making a request to your APIs, you should enable SSL on your portal to ensure that those credentials are secure. In the portal production and test environments, Apigee provides the SSL certificate required to make https:// requests. However, before you go live with your portal, you must obtain your own SSL certificate and enable SSL. For more, see Using SSL on the portal.

Configuring the SmartDocs module

Apigee implemented SmartDocs as a custom Drupal module. Use the following procedure to configure the SmartDocs module.

If you are connecting the portal to Apigee Edge for the Private Cloud, then you must ensure that SmartDocs was installed on the Edge Management Server at the time you installed Edge. For more information, see the "Install and Configuration Guide" in the documentation for the Apigee Edge for the Private Cloud.

To configure the SmartDocs module:

  1. Log in to your portal as a user with admin or content creation privileges.
  2. Select Modules in the Drupal administration menu. The list of all installed Drupal modules appears.
  3. Enable the SmartDocs module.
  4. Save the configuration.
  5. Select Modules in the Drupal admin menu.
  6. Select SmartDocs -> Permissions and ensure that "Perform administration tasks for the SmartDocs module" for "Administrator" role is enabled.
  7. Select Configuration > Dev Portal Settings in the Drupal administration menu.
  8. Set the Connection Timeout and Request Timeout to 16 seconds.
  9. Save the configuration.
  10. Configure URL settings:
    1. Select Configuration > Search and metadata > URL aliases > Settings from the Drupal menu.
    2. Set the Maximum alias length and Maximum component length to 255.
    3. Expand Punctuation.
    4. For the Left curly bracket ({) and Right curly bracket (}) settings, select No action (do not replace).
    5. Save the configuration.
  11. If your portal connects to an on-premises installation of Apigee Edge for the Private cloud (ignore this step if your portal connects to a cloud-based version of Edge):
    1. Select Configuration > SmartDocs in the Drupal administration menu.
    2. Expand the Advanced settings area.
    3. Expand the Management API override settings area.
    4. Set the Use Management API URL override checkbox.
    5. Set the Management API URL override to:

      https://routerIP:portNumber/management

      where routerIP:portNumber is the IP address and port number of the router for an Edge for Private Cloud installation. The default router port number is 59002, so the URL is typically in the form https://routerIP:59002/management. If your Edge installation has multiple routers connected to a load balancer, specify the IP and port number of the load balancer, not of a router.
    6. Save the configuration.
  12. If your portal connects to an on-premises installation of Apigee Edge for the Private Cloud, and the IP address of your Management Server is not publicly accessible:
    1. ​​Run the following cURL command from a machine that can access the Management Server:
      curl http://managment_server_ip:8080/v1/o/smartdocs/apimodels/proxyUrl
      where managment_server_ip is the IP address or your Management Server. The response will be in the form:
      {
          "authUrl": "https://api.enterprise.apigee.com/v1/users/{user}/authenticate",
          "proxyUrl": "https://apiconsole-prod.apigee.net/smartdocs/v1/sendrequest"
      }
                     
    2. Copy the URL from the proxyUrl element in the response.
    3. Select Configuration > SmartDocs in the Drupal administration menu.
    4. Expand the Advanced Settings area.
    5. Set the Edge Management server is firewalled checkbox.
    6. Paste the proxyUrl into Send Request Proxy.
    7. Save your changes.

Creating a model

A model contains all the information about the representation of your API. You can define multiple models on the portal to support different APIs, or group all of your APIs into a single model.

Each model specifies a unique internal name that also defines the base URL of the generated Drupal nodes. The URL of each Drupal node is in the form:

http://<drupalBasePath>/<internalName>/apis/<httpMethod>/<resourcePath>

where:

  • drupalBasePath: The base URL of your portal.
  • internalName: The model's internal name.
  • httpMethod: The HTTP method of the API, such as: get, put, post, or delete.
  • resourcePath: The resource path.

For example, if you specify the internal name as 'mymodel', then the URL for the generated Drupal node for a GET request to a resource named '/books' is:

http://prod-myco.devportal.apigee.com/mymodel/apis/get/books

To create a model:

  1. Log in to your portal as a user with admin or content creation privileges.
  2. Select Content > SmartDocs in the Drupal administration menu.
  3. Select New model at the top of the page.
  4. Enter the following fields:
    • Name: The model name that will be displayed across the site.
    • Internal name: As you type the Name, the internal name displays. The internal name for the model that must be unique among all models.  The internal name must contain only lowercase letters, numbers, and hyphens with no spaces. Select Edit to edit this name.
    • Description: A description of the model.
  5. Select Create Model.

After you create the model, you are redirected to the model's page. From there, you can use the Operations drop-down bx to:

  • Import a WADL file describing your API or specify the URL of a Swagger definition that describes your API.
  • Add Revision to the model
  • Modify the model Settings, including the style sheets used by the model.
  • Export the model to a file.
  • Delete the model.

Adding APIs to a model

You can add APIs to a model by:

  • Importing a WADL file containing the API definition
  • Importing a Swagger definition (Swagger 2.0 or 1.2)
  • Manually creating resources and methods

You can also import a SmartDocs JSON file into a model. This file is typically created by first exporting an existing model, editing the file, and then importing the updates. For more, see "Exporting and importing a model" below. 

Import a WADL

After you have successfully created a model, import a WADL file that describes your API. Every time you import a WADL file, you automatically create a new revision of the model.

While the WADL spec on the W3C website at http://www.w3.org/Submission/wadl/ specifies that a WADL can contain multiple <resources> tags, SmartDocs can only process a WADL file that contains a single <resources> tag. See WADL Reference for more on creating WADL files.

  1. Log in to your portal as a user with admin or content creation privileges.
  2. Select Content > SmartDocs in the Drupal administration menu.
  3. Select the model you want to update.
  4. Under Operations, select Import.
  5. Select WADL in the Choose Format dropdown on the SmartDocs import page.
  6. Select File or URL in the Upload Type dropdown.
    1. If you select File, browse to the WADL file.
    2. If you select URL, specify the URL of the WADL file.
  7. Select the Import button to import it into the model. You can now render the model.
  8. You are redirected to the model’s information page where you can now render the model.

Import a Swagger API description

After you have successfully created a model, you can import a Swagger API description. Edge supports Swagger version 1.2 and 2.0.

Swagger uses files containing JSON objects to describe an API. Every time you import a Swagger definition, you automatically create a new revision of the model.

Before you import your Swagger file, you can use tools to validate it. For example, swagger-tools provides tools to validate a Swagger document. Or, you can pass the URL of your Swagger file to this URL to validate it:

http://online.swagger.io/validator/?url=swaggerURL

Replace swaggerURL with the URL of your Swagger file.

  1. Log in to your portal as a user with admin or content creation privileges.
  2. Select Content > SmartDocs in the Drupal administration menu.
  3. Select the model you want to update.
  4. Under Operations, select Import.
  5. Select Swagger JSON or Swagger YAML in the Choose Format dropdown on the SmartDocs import page.
  6. Select File or URL in the Upload Type dropdown (you must select URL for Swagger 1.2).
    1. If you select File, browse to the Swagger file.
    2. If you select URL, specify the URL of the Swagger file.
  7. Select the Import button to import it into the model.
  8. You are redirected to the model’s information page where you can now render the model.

Manually create resources and methods

If you do not have a WADL file or Swagger definition that represents your API, you can manually add APIs to your model. Also, if you use a WADL file or Swagger definition to create your model, you can use this procedure to edit your APIs, including adding new APIs, after import.

To manually add an API:

  1. Create a new revision of the model.

    When you create the revision, you specify the single base path of all APIs in the model, meaning all APIs in a model share the same base path. For example, specify the base path as:

    https://myCompany.com/v1

    When you add resources to the model, they extend the base path.
  2. Define one or more resources for the model. The resource path combines with the base path of the model revision to specify the full URL of the resource. For example, if your resource defines a path of "/login", the full URL of the resource is:

    https://myCompany.com/v1/login
  3. Define one or more methods for each resource. A method specifies the HTTP verb that can be invoked on a resource. For example, for the "/login" resource, you support POST for login and DELETE for logout. This resource does not support other HTTP verbs, such as PUT or GET. Therefore, define two methods for the resource, one for the POST and one for the DELETE.

    The method uses the resource URL from its parent resource. Therefore, all methods with the same URL are defined under a single resource in SmartDocs.

As a general rule:

  • Create a different SmartDocs model for each unique base path in your API.
  • Define a different SmartDocs resource for each unique resource in your API.
  • Define a different SmartDocs method for each HTTP verb supported by a resource.

Creating a new revision of a model

You can only add a resource to an existing revision of a model. If the model already has a revision, you can add your resource. If the model is new and has no revisions, create a new revision.

To create a new revision of a model:

  1. Log in to your portal as a user with admin or content creation privileges.
  2. Select Content > SmartDocs in the Drupal administration menu.
  3. For the model you want to update select Add Revision under Operations.
  4. On the Add API Revision page, enter the following information:
    • Display Name: The name of the revision as it appears in the portal.
    • Version ID: A short identifier for the revision.
    • Description: A description of the revision.
    • Base URL: The base URL of all APIs in the revision of the model. A model can use different base URLs for each revision. For example, you include a version indicator in the base URL. For the first model revision, the base URL is:
      https://myCompany.com/v1
      For the next revision, the base URL could be:
      https://myCompany.com/v2
  5. Select Add Revision. You are redirected to the revision page of the model. You can now define resources on the model.

Defining a resource

A resource specifies the full URL of an API. When defining a resource, you specify the resource path, which is combined with the base URL in the model revision to create the full URL of the resource.

You can omit the resource path. In that case, the resource URL is the same as the base URL of the model revision.

To define a resource:

  1. Log in to your portal as a user with admin or content creation privileges.
  2. Select Content > SmartDocs in the Drupal administration menu.
  3. For the model you want to update, under Operations, select API Revisions to view all revisions of a model.
  4. Select a revision to edit.
  5. On the revision page, select Add Resource from the dropdown menu.
  6. On the Add Resource page, enter the following information:
    • Display Name: The name of the resource.
    • Path: The resource path, starting with "/". The value of Path is combined with the Base URL of the model revision to create the full URL of the resource.
    • Description: A description of the resource.
    • Parameters: Optionally enter the JSON object defining each parameter on the resource. These parameters are described below.
  7. Select Add Resource. You are redirected to the model page. You can now define methods on the resource.

Optionally, you can add parameters to the resource, such as template, query, and header parameters. All resource parameters are inherited by any methods defined on that resource. Therefore, if you define a query parameter on the resource, all methods added to that resource must support that query parameter.

Alternatively, you can define parameters on a method. For example, a POST method might support query parameters that are not supported by a DELETE method. Therefore, add any parameters specific to a method when you define the method, as described below.

The following image shows an existing SmartDocs page for the Apigee Approve or Revoke Developer App API with each type of parameter highlighted:

Each parameter type is defined by a JSON object:

Type

JSON object

Notes

Template

{
 "dataType": "string",
 "defaultValue": "",
 "description": "The organization name.",
 "name": "org_name",
 "required": true,
 "type": "TEMPLATE"
}

Template params are always required, so set required to true, and omit the value to  defaultValue.

The description value appears in a popup when the user hovers over the URL in a SmartDocs page.

Query

{
 "dataType": "string",
 "defaultValue": "",
 "description": "The location.",
 "name": "w",
 "required": true,
 "type": "QUERY"
}

Required query params can still specify a defaultValue, but often do not.

For optional query params, set required to false and specify a value to defaultValue.

Header

{
 "dataType": "string",
 "defaultValue": "application/json",
 "description": "Specify as <code>application/json</code>.",
 "name": "Content-Type",
 "required": true,
 "type": "HEADER"
}

Notice how you can use HTML tags in the description.  

A template parameter defines a variable in the resource path. For example, you define two template parameters on the resource. Notice how each parameter definition in the parameter array is separated by a comma:

[
 {
  "dataType": "string",
  "defaultValue": "",
  "description": "Mention the organization name.",
  "name": "org_name",
  "required": true,
  "type": "TEMPLATE"
 },
 {
  "dataType": "string",
  "defaultValue": "",
  "description": "Mention the user email.",
  "name": "developer_email",
  "required": true,
  "type": "TEMPLATE"
 }
]

You can then use the template parameters in the resource Path definition, enclosed in "{}". For example, set the path to:

/login/{org_name}/{developer_email}

In the SmartDocs API page, the user must edit the URL to specify the org_name and developer_email portion of the URL before they can submit a request.

Defining a method

Define one or more methods for each resource. The method definition specifies an HTTP verb that can be invoked on the resource. A resource can have a single method defined on it, or multiple methods.

As part of defining the method, specify any parameters used by the method, including query and header parameters. See the description above for resource for information about adding parameters to a method.

The following image shows an existing SmartDocs page for the Apigee Create Developer API with each area of the page highlighted with the corresponding value that you set when defining a method:

The next image shows the same page but with the Description of the Request Body selected:

To define a method:

  1. Log in to your portal as a user with admin or content creation privileges.
  2. Select Content > SmartDocs in the Drupal administration menu.
  3. For the model you want to update, under Operations, select API Revisions to view all revisions of a model.
  4. Select a revision to edit.
  5. On the revision page, select Add Method from the dropdown menu for one of the resources.
  6. On the Edit Method page, enter the following information:
    • Display Name: The name of the API, which also becomes the title of the Drupal page for the API.
    • Description: Describe the API.
    • Method Verb: The HTTP verb type.
    • Security Schemes: Specify the authentication mode, if any, for the method. For more, see Configuring the SmartDocs authentication type.
    • Content Type: The content type of the request and response. See the section below about configuring different authentication methods.
    • Parameters: (Optional) Any query or header parameters for the method. See the description above for adding a parameter to a resource for more information.
    • Request Body Documentation: (Optional) Describe the request body. POST and PUT methods take a request body. You can use this area to describe it. If you omit this value, the Description link under Request Body is omitted from the generated SmartDocs page.
    • Request Body Example: (Optional) Show an example of a request body, typically as a JSON object or as XML. For the POST and PUT verbs, the Request Body Example is passed as part of each request. Users of the SmartDocs page edit this example before they submit a request to the API. If you omit this value, the Value link under Request Body is omitted from the generated SmartDocs page.
    • Tags: An array of tags associated with the API. SmartDocs uses tags to group similar APIs together. For example, you might apply the tag "Statistics" to all APIs about statistics. You can group APIs from different resources under a single tag. if they all use the same tag.
  7. Select Add Method. You are redirected to the model page. You can now render and publish your method.

Rendering a model

After you add APIs to a model, you can render the model. Rendering converts the model's description of the API into Drupal nodes. When rendering completes, you will have a single Drupal node for each API, where each Drupal node corresponds to an HTML page.

You can choose to render the entire model at once, or selct individual APIs for rendering. 

To render a model:

  1. Log in to your portal as a user with admin or content creation privileges.
  2. Select Content > SmartDocs in the Drupal administration menu.
  3. For the model you want to render, select API Revisions under Operations.
  4. Select the revision you want to render. You can only render nodes from a single revision of the model.
  5. Select the methods to render.
  6. Select Render Nodes from the Update options dropdown.
  7. Click Update.
  8. A loading screen appears to view progress on your nodes being rendered.
    After the nodes have been rendered, the ID of the Drupal node for each API appears under the Node Association column of the model. Click on the link in the Node Association column to see the rendered node.

Instead of selecting Render Nodes, you can select Render and publish nodes to render and immediately publish the APIs as a Drupal node. 

Publishing nodes

A node is not visible to portal users until it is published. You can optionally choose to publish nodes during the rendering process. If you do choose not to publish the nodes, then you have to manually publish them after rendering completes.

To publish a node:

  1. Log in to your portal as a user with admin or content creation privileges.
  2. Select Content > SmartDocs in the Drupal administration menu.
  3. For the model you want to publish, select API Revisions under Operations.
  4. Select the revision you want to publish. You can only publish nodes from a single revision of the model.
  5. Select the methods to publish.
  6. Select the nodes in the revision to publish.
  7. Select the Publish Nodes from the Update options dropdown.
  8. Click Update.
  9. Navigate to the node by selecting the node ID under the Node Association column.

By default, the Drupal URL to a published API node is in the form: http://<drupalBasePath>/<internalName>/apis/<httpMethod>/<resourcePath>. Use the following procedure to control the form of the URL:

  1. Log in to your portal as a user with admin or content creation privileges.
  2. Select Configuration > Search and metadata > URL aliases > Patterns in the Drupal administration menu.
  3. Under Pattern for all SmartDocs Method paths specify how you want to generate the path.
  4. Select Save configuration.

Because of caching on the portal, you might not see your model pages appearing immediately after publishing them. If necessary, you can manually clear the SmartDocs HTML cache by using the following procedure:

  1. Log in to your portal as a user with admin or content creation privileges. 
  2. Select Configuration > SmartDocs in the Drupal administration menu.
  3. Select the Rebuild SmartDocs model caches button.

Unpublishing a node

You can unpublish a published node at any time. Unpublishing a node makes it invisible to portal users.

To unpublish a node:

  1. Log in to your portal as a user with admin or content creation privileges.
  2. Select Content > SmartDocs in the Drupal administration menu.
  3. For the model you want to unpublish, select API Revisions under Operations.
  4. Select the model revision of the node you want to unpublish.
  5. Select the nodes in the revision to unpublish.
  6. Select the Unpublish Nodes from the Update options dropdown.
  7. Click Update.

Viewing the revision of a model

You create a new revision of a model by importing a new WADL file or Swagger definition into an existing model, or by manually creating a new revision. After creating the new revision, you can render and publish the revision, which replaces the currently published Drupal nodes.

You can render and publish nodes from multiple revisions at the same time. Meaning if you have five revisions of a model, you can publish nodes from any or all revisions. However, publishing an API in one model that is the same as a published node from another model unpublishes the older version of the API and replaces it with the one from the most recently published API. 

To see the revision of a model:

  1. Log in to your portal as a user with admin or content creation privileges.
  2. Select Content > SmartDocs in the Drupal administration menu.
  3. For the model you want to update, select API Revisions under Operations.
  4. Select the model revision you want to view.
  5. Render and publish the nodes as described above.

Editing a node

After you render a node, you can edit it by using the Drupal editor. For example, you can edit the HTTP verb and description of an API, or add a new query or header parameter to the API. You can edit nodes created from a WADL file or Swagger definition, or nodes that created manually.

You can also edit the original WADL file or Swagger definition. When you are done with editing, import the WADL file or Swagger definition back into the model as a new revision, then render and publish your changes as described above. 

To edit a node by using the Drupal editor:

  1. Log in to your portal as a user with admin or content creation privileges.
  2. Browse to the Drupal node corresponding to the API documentation that you want to edit.
  3. Select Edit to use the Drupal editor.
  4. After your edits are complete, select Update Method.

Alternatively, you can edit the node from the SmartDocs model:

  1. Log in to your portal as a user with admin or content creation privileges.
  2. Select Content > SmartDocs in the Drupal administration menu.
  3. For the model you want to update, select API Revisions under Operations.
  4. Select the model revision you want to publish.
  5. Select Edit method in the Operations dropdown for the method that you want to edit.

To delete a node:

  1. Log in to your portal as a user with admin or content creation privileges.
  2. Select Content > SmartDocs in the Drupal administration menu.
  3. For the model you want to update, select API Revisions under Operations.
  4. Select the model revision you want to publish.
  5. Select Delete method in the Operations dropdown for the method.
    Caution: Deleting the node also removes the API from the model. If you only want to unpublish the API so that it is hidden from portal users, but do not want to delete it from the model, you should unpublish the node as described above. 

Exporting and importing a model

SmartDocs lets you export an existing model to a file. For example, you might define a production and a staging environment. You then make all of your SmartDocs edits in the staging environment. When you are ready to release your APIs, you export the staging model and import it into the production model.

Importing a model creates a new revision of the model. SmartDocs attempts to match existing APIs in the model with imported APIs. If SmartDocs detects a match, the import updates the Drupal node corresponding to the existing API. If SmartDocs does not detect a match, then the import creates a new Drupal node for the API.

For example, you have a POST API the corresponds to a Drupal node with an ID of 91. You then import a model and SmartDocs detects a match of a POST API in the imported model to the existing POST API. Any updates to the POST API then update Drupal node 91. If SmartDocs does not detect a match, it creates a new Drupal node with a new ID.

Drupal performs the match by using the following characteristics of the API:

  • internalName: The internal model name.
  • httpMethod: The HTTP method of the API, such as: GET, PUT, POST, or DELETE.
  • resourcePath: The resource path.
  • query params: Any query parameters used by the API.

If all four characteristics of an imported API match an existing API in the model, then SmartDocs updates the existing Drupal node.

The exported model is represented by a single JSON object with entries for resources and methods. That means you can edit the exported model to modify a resource or method, and then reimport the model. If you do edit the JSON object, do not modify the following fields:

  • revisionNumber
  • createdTime
  • modifiedTime
  • apiRevisionId
  • resourceId

To export a model:

  1. Log in to your portal as a user with admin or content creation privileges.
  2. Select Content > SmartDocs in the Drupal administration menu.
  3. For the model you want to export, select Export under Operations.
  4. Select the export file type as SmartDocs JSON.
  5. Select the Export button.
  6. You are prompted to save the file to disk or open it in an editor.

To import a model:

  1. Log in to your portal as a user with admin or content creation privileges.
  2. Select Content > SmartDocs in the Drupal administration menu.
  3. For the model you want to import, select Import under Operations.
  4. Select SmartDocs JSON in the Choose Format dropdown.
  5. Select File or URL in the Upload Type:
    1. If you select File, browse to the JSON file.
    2. If you select URL, specify the URL of the SmartDocs JSON file.
  6. Select the Import button to import it into the model.
  7. You are redirected to the model’s information page where you can now render the model. Note that the import creates a new revision of the model.
  8. Render and publish the nodes.

Editing the SmartDocs template

The SmartDocs template defines how your Drupal nodes appear on the screen. A template includes CSS files, JavaScript files, and template code as a Handlebars .hbr file. Each SmartDocs model can use the same template or a custom template unique to the model.

By default, models reference template files located at https://smartdocs.apigee.com. To add custom JavaScript or CSS files to the SmartDocs template, put the files on a server and make sure that the server is accessible to the portal. Alternatively, you can use the Drupal Media module to upload your assets directly to the portal for reference. For example, you can start by copying all of the JavaScript and CSS files from https://smartdocs.apigee.com, editing them, and then putting them on a server accessible by your portal.

To modify the template for an individual model:

  1. Log in to your portal as a user with admin or content creation privileges.
  2. Select Content > SmartDocs in the Drupal administration menu.
  3. For the model you want to edit, select Settings under Operations.
  4. Edit the template as necessary.
  5. Save the template.
  6. Browse to a Drupal node. You should see your template changes on the page.

You can upload a custom template file as a Handlebars .hbr file that is then used by all models.

To upload a custom template .hbr file for all models:

  1. Log in to your portal as a user with admin or content creation privileges.
  2. Select Configuration > SmartDocs in the Drupal administration menu.
  3. Expand the Advanced Settings area of the page. 
  4. Select the Choose File button, and navigate to the .hbr file.
  5. Select Upload.
  6. Save the configuration.

If your portal does not have an external internet connection, you can reference the templates embedded within the SmartDocs module.

To use the template embedded in the SmartDocs module:

  1. Log in to your portal as a user with admin or content creation privileges.
  2. Select Configuration > SmartDocs in the Drupal administration menu.
  3. Expand the Advanced Settings area.
  4. Expand the Management API Override Settings area.
  5. Set the Use Local SmartDocs JS/CSS checkbox.
  6. Save the configuration.

Configuring the SmartDocs authentication type

APIs defined in SmartDocs can either be open, meaning no authentication credentials are required to access them, or secure. A secure API requires that you pass credentials when making a call to the API.

For a secure API, SmartDocs supports the following types of authentication:

  • Basic authentication - Pass basic authentication credentials as a username and password pair. If you do not specify to use OAuth as the credential type, the API defaults to using basic authentication.
  • OAuth 2.0 - A third-party service provider authenticates the user's credentials, ensures that the user has authorization to the API, and then issues an access token. When you make a SmartDocs request to a protected API, SmartDocs builds the request and sends it to the service provider. The service provider then validates the token and ensures that it has not expired.
  • Custom token - Pass a token value as a header or query parameter to each request.

For each type of authentication, you create a security scheme that defines the characteristics of the authentication. For example, for custom token authentication, the security scheme defines how the token is passed (header, query param, body param) and the name of the token.  

A security scheme is associated with a specific revision of a model. Therefore, if you create a new revision of a model, you have to redefine the security schemes for that revision 

In a WADL file, you specify if an API requires authentication by using the <apigee:authentication> Apigee tag, as shown below:

<method id="statusespublic_timeline" name="GET" apigee:displayName="PublicTimeline">
    ...
    <apigee:authentication required="true"/>
</method> 

If the API is open, set the required attribute to false.

Notice that you cannot specify the type of authentication in the WADL file. You do that by editing the node in Drupal. For more information on WADL files, see WADL Reference.

On the API page in Drupal, SmartDocs adds the following button to let users specify their basic authentication credentials:

If you edit the node to set the authentication type to OAuth, then SmartDocs adds the following button to the page:

For custom token, SmartDocs adds:

Configuring basic authentication

If you use basic authentication with your API, then you only have to specify the <apigee:authentication> tag in the WADL file that you use to create the model.

To apply basic authentication to methods created from a source other than a WADL file:

  1. Log in to your portal as a user with admin or content creation privileges.
  2. Select Content > SmartDocs in the Drupal administration menu.
  3. For the desired model, select API Revisions under Operations.
  4. For the model revision you want to edit, select Security Settings under Operations.
  5. Select Add Security Scheme.
  6. Specify the name of the security scheme.
  7. Select Basic as the Type.
  8. Select Submit.
  9. For each method in the model, edit the method to set its Security Scheme to your basic scheme.
    1. Select Content > SmartDocs in the Drupal administration menu.
    2. For the desired model, select API Revisions under Operations.
    3. For the model revision you want to edit, select Revision Details under Operations.
    4. Select Edit Method for the API that you want to edit.
    5. Select the Security Scheme for the API.
    6. Save the API. 

Configuring OAuth 2.0 authentication

You can configure a model to use OAuth 2.0 in SmartDocs, instead of the default of basic authentication. You configure OAuth in two locations:

  1. Create a security scheme for each revision of a model under Security Settings for the revision.
  2. Specify the Client ID and Client Secret for all revisions of the model under Settings for the model.

To enable OAuth:

  1. Log in to your portal as a user with admin or content creation privileges.
  2. Select Content > SmartDocs in the Drupal administration menu.
  3. For the desired model, select API Revisions under Operations.
  4. For the model revision you want to edit, select Security Settings under Operations.
  5. Select Add Security Scheme.
  6. Specify the name of the security scheme.
  7. Select OAuth 2.0 as the Type.
  8. Set the Grant Type.
  9. Enter the values in the Authorization URL fields. The Authorization URL is used to obtain the access token.
  10. Set the Authorization Verb as GET or POST.
  11. Enter the Access Token URL. The Access Token URL is the URL used to exchange the request token for an access token.
  12. Enter the Access Token param name.
  13. Use In to specify how to pass the token: Header, Query, or Body.
  14. Set the OAuth Scopes.
  15. Select Submit.
  16. Select Content > SmartDocs in the Drupal administration menu.
  17. For the model, select Settings in the Operations drop-down.
  18. Enter the values in the Client ID and Client Secret.
  19. Select Save template authentication settings.
  20. For each method in the model, edit the method to set its Security Scheme to your OAuth security scheme.
    1. Select Content > SmartDocs in the Drupal administration menu.
    2. For the desired model, select API Revisions under Operations.
    3. For the model revision you want to edit, select Revision Details under Operations.
    4. Select Edit Method for the API that you want to edit.
    5. Select the Security Scheme for the API.
    6. Save the API. 

Configuring custom token authentication

You can configure a model to use custom token authentication.

To enable custom tokens:

  1. Log in to your portal as a user with admin or content creation privileges.
  2. Select Content > SmartDocs in the Drupal administration menu.
  3. For the desired model, select API Revisions under Operations.
  4. For the model revision you want to edit, select Security Settings under Operations.
  5. Select Add Security Scheme.
  6. Specify the name of the security scheme.
  7. Select Apikey as the Type.
  8. Set the Param Name containing the token.
  9. Use In to specify how to pass the token: HeaderQuery, or Body.
  10. Select Submit.
  11. For each method in the model, edit the method to set its Security Scheme to your token scheme.
    1. Select Content > SmartDocs in the Drupal administration menu.
    2. For the desired model, select API Revisions under Operations.
    3. For the model revision you want to edit, select Revision Details under Operations.
    4. Select Edit Method for the API that you want to edit.
    5. Select the Security Scheme for the API.
    6. Save the API. 

 

Help or comments?