Was this helpful?

Apigee added the Beta release of SmartDocs to the 14.04.16 release of the Developer Services portal. 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 is fully supported on all browsers supported by the portal except for IE9. For IE9, you cannot upload attachments to a SmartDocs API. In addition, for IE9 support, you must ensure that your SmartDocs model uses the templates at  https://smartdocs.apigee.com/2/ instead of https://smartdocs.apigee.com/1/. For more information, see the section below on editing the SmartDocs template.

SmartDocs portal example

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.
  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. Import a WADL file or Swagger definition into the model. The WADL file or Swagger definition contains the information about your API.
  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, by using the SmartDocs on-page editor, or by editing the original WADL file or Swagger definition.
  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 an on-premises version of Apigee Edge, 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 On-Premises Deployment Kit.

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 Configuration > Dev Portal Settings in the Drupal administration menu.
  6. Set the Connection Timeout and Request Timeout to 16 seconds.
  7. Save the configuration.
  8. 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.
  9. If your portal connects to an OPDK installation of Apigee Edge, and that installation of Edge has no external internet connection:
    1. Select Content > SmartDocs > Settings 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://domainName:portNumber/management where domainName:portNumber is the domain name and port number of your on-premises Edge OPDK installation.
    6. Save the 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 name, called the machine readable name, that also defines the base URL of the generated Drupal nodes. The URL of each Drupal node is in the form:

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

where:

  • drupalBasePath: The base URL of your portal.
  • machineModelName: The machine model 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 machine readable 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 Add at the top of the page.
  4. Enter the following fields:
    • Display Name: The model name that will be displayed across the site.
    • Machine Readable Name: The internal identifier for the model that must be unique among all models.  The machine readable name must contain only lowercase letters, numbers, and underscores with no spaces.
    • Description: A description of the model
    • Bootstrap Settings: If your site is using Bootstrap, specify the Bootstrap version.
  5. Select Create Model.

After you create the model, you are redirected to the SmartDocs import page. From that page, you can import a WADL file describing your API or specify the URL of a Swagger definition that describes your API. The following section describes both options.

To import a WADL:

After you have successfully created a model, import a WADL file that describes your API: 

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. Select WADL File in the Choose Format dropdown on the SmartDocs import page.
  2. Select Upload or URL Path in the WADL Options dropdown.
    • If you select Upload, browse to the WADL file and select Upload.
    • If you select URL Path, specify the URL of the WADL file  and select Upload.
  3. After the  upload complete, select the link corresponding to the file name to see if there were any errors.
  4. If you want to use OAuth as the authentication mechanism for your APIs, perform the steps described in Configuring OAuth 2.0 authentication before you import the WADL.
  5. Select the Import button to import it into the model.
    You are redirected to the model’s information page where you can now render the model.

To import a Swagger API description:

After you have successfully created a model, you can import a Swagger API description. Swagger uses files containing JSON objects to describe an API.  

  1. Select Swagger in the Choose Format dropdown on the SmartDocs import page.
  2. Specify the Swagger URL, the URL corresponding to the top-level Swagger file describing your API.
  3. If you want to use OAuth as the authentication mechanism for your APIs, perform the steps described in Configuring OAuth 2.0 authentication before you import the Swagger definition.
  4. Select the Import button to import it into the model.
    You are redirected to the model’s information page where you can now render the model.

Rendering a model

After you import the WADL or Swagger description into a model, you can render the model data. 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.

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. Select the revision you want to render. You can only render nodes from a single revision of the model.
  4. Select Render Nodes from the Update options dropdown.
  5. Click Update.
  6. You are redirected to a confirmation page with the following options:
    • Publish nodes immediately: Select this option to publish the nodes after rendering completes.
    • (Optional) Drupal Specific Template Settings: This option only appears if you did not specify the Bootstrap version when you created the model. If you specified it when you created the model, this option does not appear.
  7. Select Render Nodes.
  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.

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. Select the revision you want to publish.
  4. Select the nodes in the revision to publish.
  5. Select the Publish Nodes from the Update options dropdown.
  6. Click Update.

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. Select the revision you want to unpublish.
  4. Select the nodes in the revision to unpublish.
  5. Select the Unpublish Nodes from the Update options dropdown.
  6. Click Update.

Creating a new version of a model

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

To create a new version of a model:

  1. Log in to your portal as a user with admin or content creation privileges.
  2. Select Content > SmartDocs > Import in the Drupal administration menu.
  3. Select the model you want to update.
  4. Import the new WADL or Swagger definition.
    You are redirected back to the model page. Notice that the revision of the model has been incremented by one and that the latest revision is current.
  5. Select + Revision Select to make a different revision current.
  6. Render and publish the nodes as described above.

Editing a node

After you render a node, you can edit it by using one of three editing modes. The first two types of editing, using the Drupal editor and using the SmartDocs in-page editor, let you edit a subset of the API information within the Drupal environment. For example, you can edit the HTTP verb and description of an API, but you cannot add a new query or header parameter to the API.

If you want complete editing control, edit the original WADL file or Swagger definition. This is the only way to add or delete APIs, add or remove header and query parameters, and edit the resource URL.  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. 

The following table describes these different modes and the types of information that you can modify in each mode:

Editing mode

Use

Drupal editor

From the Drupal editor, you can edit a Drupal node to modify the following information about an API:

  • API Name
  • Description
  • Verb (GET, PUT, POST, DELETE)
  • Type: the media type
  • Tags
  • Authentication type

SmartDocs in-page editor

Lets you edit the API directly on the Drupal page, without opening a separate editor. From the SmartDocs in-page editor, you can edit the following information:

  • API Name (Not supported in the SmartDocs Beta)
  • Description (Not supported in the SmartDocs Beta)
  • Header and query parameter descriptions
  • Request/response descriptions
  • Request body description

WADL file or Swagger definition

Edit the WADL file or Swagger definition to edit any API information. After editing, import the WADL file or Swagger file as a new revision of your model as described above.

You can edit all parts of the model, including adding new APIs and deleting existing APIs. This is the only way to edit add/remove APIs, edit the resource URL, and add/remove header and query parameters.

To edit a node by using the Drupal editor or the SmartDocs in-page 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. The following menu options appear at the top of the node:
  3. Select Edit Drupal Node to use the Drupal editor, and Edit SmartDoc to use the in-page editor.
  4. If you choose Edit SmartDoc, then after you complete your edits, you have to synchronize your changes with the model:
    1. Select Content > SmartDocs > Models in the Drupal administration menu.
    2. Select the model name.
    3. Select the nodes that you edited. Note that if you select all nodes, then you will synchronize your edits along with edits made by anyone else.
    4. In the Update Options dropdown, select  Sync Nodes to SmartDocs.
    5. Select the Update button.

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:

  • machineModelName: The machine 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 > Export in the Drupal administration menu.
  3. Select the model name.
  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 > Import in the Drupal administration menu.
  3. Select the model name. The model must already exist.
  4. Select SmartDocs JSON in the Choose Format dropdown.
  5. Select Upload or URL Path in the SmartDocs JSON Options dropdown.
  6. If you select Upload, browse to the JSON file and select Upload.
  7. If you select URL Path, specify the URL of the SmartDocs JSON file  and select Upload.
  8. After the upload complete, select the link corresponding to the file name to see if there were any errors.
  9. Select the Import button to import it into the model.
  10. 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.
  11. 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.

Each SmartDocs model can use the same template or a custom template unique to the model. After you render your nodes, you can modify the template to alter the way the page appears.

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.

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

To modify the template:

  1. Log in to your portal as a user with admin or content creation privileges.
  2. Select Content > SmartDocs > Setting > modelName in the Drupal administration menu.
  3. Edit the template as necessary.
  4. Save the template.
  5. Browse to a Drupal node. You should see your template changes on the page.

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 Content > SmartDocs > Setting 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 two types of authentication:

  • Basic authentication (default) - 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 and signs the request and sends it to the service provider. The service provider then validates the token and ensures that it has not expired.

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.

If authentication is required for an API, by default, SmartDocs uses basic authentication. 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:

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. Because basic authentication is the default, no other configuration is necessary.

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 must enable and configure OAuth at the time you import the WADL file or Swagger definition.

You must specify OAuth 2.0 as the authentication type for an API before you publish it. Therefore, when you render the nodes of the model, do not select the option to publish them at the time of rendering. 

To enable OAuth when importing the WADL or Swagger definition:

  1. After selecting the WADL or Swagger definition for the model, expand the OAuth Configuration area of the page.
  2. Select Enable OAuth.
  3. Enter the values in the Client ID, Client Secret, and Authorization URL fields.
  4. Set the Authorization Verb as GET or POST.
  5. Enter the Access Token URL and Access Token Type.
  6. Enter the Access Token param name.
  7. Select the Client Authentication Name.
  8. Select Import
    The portal creates the model and displays the model's OAuth callback URL. You must specify that callback URL when configuring the OAuth provider. You do not need to specify the the full URL to the OAuth provider, just that part in the form: http://{portalDomain}/smartdocs/oauth.
  9. Render the model nodes as described above, but do not publish them.
  10. Before you publish the nodes, for each node in the model that supports OAuth 2.0:
    1. Under Node Association in the model, select the node ID to open the Drupal page.
    2. Select Edit Drupal Node on the Drupal page.
    3. Set the authschemes to OAUTH2WEBSERVER.
    4. Save your changes. 

 

Help or comments?

  • Something's not working: See Apigee Support
  • Something's wrong with the docs: Click Send Feedback in the lower right.
    (Incorrect? Unclear? Broken link? Typo?)