Using SmartDocs to document APIs

You're viewing Apigee Edge documentation.
Go to the Apigee X documentation. info

SmartDocs lets you document your APIs on the Drupal 7 developer 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.

From your developer portal home page, click APIs in the top navigation bar to view the API Documentation page.

There are two APIs documented on the portal: Hello World and Pet Store Example.

The Hello World API was created from the mock target OpenAPI Specification, mocktarget.yaml. For more information, see https://github.com/apigee/api-platform-samples/tree/master/default-proxies/helloworld/openapi.

The Pet Store Example API was created from the classic pet store demo.

Explore the Hello World API:

  1. Click Hello World API. The Hello World API summary page is displayed:
  2. Click View API affirmation. The SmartDocs for this resource is displayed:
  3. Click Send this request.
  4. View the response returned: 
    HTTP/1.1 200 OK
Connection:
keep-alive
Content-Length:
18
Content-Type:
text/html; charset=utf-8
Date:
Tue, 21 Jun 2016 21:49:32 GMT
ETag:
W/"12-Jb9QP1bUxNSmZkxQGt5KLQ"
X-Powered-By:
Apigee
<H2>I <3 APIs</H2>
  5. Click the Request tab to view the request, or the cURL tab to view the corresponding cURL call.

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, OpenAPI (formerly Swagger) specification, 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 OpenAPI Specification. When you are done editing the WADL file or OpenAPI Specification, import it back into the model as a new revision, then render and publish your changes.
  7. Enable TLS. Because SmartDocs can send authentication credentials to your backend as part of making a request to your APIs, you should enable TLS on your portal to ensure that those credentials are secure. In the portal production and test environments, Apigee provides the TLS certificate required to make https:// requests. However, before you go live with your portal, you must obtain your own TLS certificate and enable TLS. For more, see Using TLS on the portal.

About SmartDoc models and templates

When you create a model in your portal, the model is actually stored in your Edge organization, not in Drupal. A model is a big block of JSON with an internal name (such as "my-smartdocs-api"), and it defines the structure of an API. Your portal, on the other hand, renders the model in HTML and provides an editing interface for the model. Any updates to the API in the portal are automatically pushed back to the source model.

Stored in organization

Stored in Drupal

models

templates

Drupal nodes with editing functionality

Assume that you have multiple portals in your organization (for example, dev, stage, and production). In Pantheon, you move a portal from one environment to another. Each instance of the portal looks like it contains its own model, but all of them are really referencing the source model. If you edit the API in dev, the model is updated, and the changes appear in production. Likewise, if you delete a model in dev, the source is deleted, and it's no longer available in production.

Templates control the look and feel of your SmartDocs, and those templates (governed by Handlebars and CSS files) are stored with each portal instance. So each portal can theoretically use a unique template for each model. However, one of the conveniences of the rendering framework is that a default template (either the Apigee default or a template you provide) is automatically applied to each model.

The following diagram shows the relationship between models and portals. The green arrows show automatic synchronization.

The following cURL command lists all the models in your organization:

curl -v https://api.enterprise.apigee.com/v1/o/{your_org}/apimodels/ -u edge_org_admin@example.com

Configuring the SmartDocs module

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

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 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. Click Save configuration.
  11. If your developer portal will be exposed to users in an internal network without access to the internet or if a subset of your APIs are on a private network, configure the SmartDocs API proxy URL, as follows:
    1. Select Configuration > SmartDocs in the Drupal Administration menu.
    2. Expand Advanced Settings.
    3. Update the SmartDocs proxy URL field as follows: <host>/smartdocs/v1/sendrequest.
      The inline help should provide the required value for your environment. For example:
      https://api-us-east-1-enterprise.apigee.com/smartdocs/v1/sendrequest

      This field defaults to https://apiconsole-prod.apigee.net/smartdocs/v1/sendrequest
    4. Click Save configuration.

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

When you create a model, it's stored in your Edge organization as the source for the API structure. For more information, see About SmartDoc models and templates.

  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 an OpenAPI Specification 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 an OpenAPI Specification (OpenAPI 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.

Video: Watch a short video to learn how to add APIs to a SmartDocs model by importing an OpenAPI Specification.

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.

  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. Click Import 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 an OpenAPI Specification

After you have successfully created a model, you can import an OpenAPI (formerly Swagger) Specification. Edge supports OpenAPI version 1.2 and 2.0.

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

To import an OpenAPI Specification:

  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 OpenAPI 1.2).
    1. If you select File, browse to the OpenAPI Specification.
    2. If you select URL, specify the URL of the OpenAPI Specification.
  7. Click Import 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 OpenAPI Specification that represents your API, you can manually add APIs to your model. Also, if you use a WADL file or OpenAPI Specification 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.

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. Click Rebuild SmartDocs model caches.

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 OpenAPI Specification 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 OpenAPI Specification, or nodes that created manually.

You can also edit the original WADL file or OpenAPI Specification. When you are done with editing, import the WADL file or OpenAPI Specification 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.

The portal has a built-in report which displays information about any node rendered by a SmartDocs model which no longer refer to a valid methods of the model. Access the report by selecting Reports in the Drupal menu, and then selecting the report named SmartDocs node status.

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. Click Export.
  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. Click Import 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. Each SmartDocs model can use the same default template or you can manually customize the template used for an individual model.

The SmartDocs template includes a template file coded as a Handlebars .hbr file, CSS files, and JavaScript files. With Handlebars, much of the content is variable-driven using embedded handlebars expressions, such as&123;&123;body}}. A list of the existing Handlebar expressions is provided in a comment at the top of the file. For information about using Handlebars to customize your templates, see http://handlebarsjs.com.

The following sections describe how to upload a custom SmartDocs template file for use by all new models or for when you are importing new APIs into an existing model, how to restore the original default SmartDocs template file, and how to modify the SmartDocs template for an individual model.

Uploading a custom SmartDocs template file

You can upload a custom SmartDocs template file, as a Handlebars .hbr file, to use as the default template when creating new models or importing new APIs into an existing model.

If you'd like to use the default SmartDocs template file as a starting point when creating your custom SmartDocs template file, you can download a copy from: profiles/apigee/modules/custom/devconnect/smartdocs/templates/smartdocs.hbr

To upload a custom SmartDocs template file:

  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. Under Upload customized method template, click Choose File, and navigate to the Handlebars .hbr file.
  5. Click Upload.
  6. Click Save configuration.

Restoring the default SmartDocs template file

You can restore the default SmartDocs template file. Once restored, the default SmartDocs template file will be used when creating new models or importing new APIs into an existing model.

To restore the default SmartDocs template file:

  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. Under Upload customized method template, click Remove adjacent to the custom SmartDocs template file.
  5. Click Save configuration.

Modifying the SmartDocs template for an individual model

You can modify the template used for an individual model.

To modify the template for an indvidual 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. In the Method Template area, edit the template as required.
  5. Click Save template.
  6. Browse to a Drupal node. You should see your template changes on the page.

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: Header, Query, 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.

Deleting a model

When you delete a model (Content > SmartDocs, Delete in the Operations field in Drupal), the model is deleted from your Edge organization. That means if other portals are referencing the model, the model is no longer available. For more information, see About SmartDoc models and templates.