Content Development Guidelines

Guidelines that API providers can use to manage API content such as API documentation and legal agreements.

Note: For information about tagging API documentation for visibility by different audiences, see API Documentation Tagging.

API Platform Version: 8.1 and later

Table of Contents

Content Management General Information:
  1. What document management tasks can I perform in the platform?
  2. What are the general HTML coding guidelines?
  3. What are reset.css and base.css and why would I use them?
  4. Does the platform require that HTML files be saved in a specific code format?
API Documentation:
  1. What API documentation publishing options does the platform provide?
  2. What document styles can I use for API documentation?
  3. Can I add other types of content to my API documentation?
  4. How do I edit HTML page content for API documentation?
  5. Who can edit API and legal agreement content?
  6. How do I organize my API and legal agreement documentation files?
  7. How do I upload my API documentation in a ZIP file?
  8. Can I link to an external site?
  9. What style sheets do I use for my HTML API documentation?
  10. How do I set the default API documentation page using a parameter file?
  11. Can I upload existing API documentation and use it in the platform?
  12. How do I upload API documentation?
  13. How do I update API and legal agreement documentation I've added to the platform?
  14. How do I test updated API documentation?
  15. How do I configure my API documentation so it's searchable in the platform?
Linking in API Documentation:
  1. How do I link to another location in the same document in Default Theme/Hermosa Theme?
  2. How do I link to a content file in the same folder in Default Theme/Hermosa Theme?
  3. How do I link to a content file in a subfolder in Default Theme/Hermosa Theme?
  4. How do I link to a content file in a parent folder in Default Theme/Hermosa Theme?
  5. How do I link to a platform content page in Default Theme/Hermosa Theme?
  6. How do I link to a content page in a platform subfolder in Default Theme/Hermosa Theme?
  7. How do I link to an external site or document in Default Theme/Hermosa Theme?
  8. How do I link to another API documentation file in the documentation folder in Default Theme/Hermosa Theme?
  9. When do I need to reference the tag_lib.min.js file?
  10. How do I reference the tag_lib.min.js file?
Using File Explorer:
  1. What is File Explorer and what functionality does it offer?
  2. How do I add a file to the API documentation table of contents?
  3. How do I set the default API documentation page using File Explorer?
  4. How do I set the file display name in the API documentation table of contents?
  5. How do I rename a file in File Explorer?
  6. How do I view a file in File Explorer?
  7. How do I delete a file using File Explorer?
Using Swagger:
  1. What is Swagger and how does it work?
  2. What are the Swagger controls and how do I edit page content?
  3. What style sheets do I use for my Swagger documentation?
  4. Can I mix Swagger and HTML files in my API documentation?
Legal Agreements:
  1. How do I upload my API legal agreements?
  2. What style sheets do I use for my API legal agreements?

Content Management General Information:

What document management tasks can I perform in the platform?

Within the platform, editing of API and Legal Agreement content is limited to:

  • Uploading API and legal agreement documents via the File Explorer.
  • Defining name and description of legal agreements.
  • Activating / deactivating visibility of legal agreements in API wizards.
  • Downloading legal agreement usage reports.

Development of document content must be performed outside the platform, with the exception of Swagger API documentation which is entered directly into the templates in the API > Documentation section.

Back to top

What are the general HTML coding guidelines?

Following the guidelines below will help ensure your fileset is consistent in structure, with clean, well-formed HTML that will look correct when viewed under varying circumstances such as in different browsers and in search results.

Recommendations:

  • Use an HTML editor that doesn’t add extra tags into your code. Working with HTML in a word processing program, for example, can result in complex HTML with many extra tags. This can be difficult to work with and to debug when needed. There are free HTML editors available for download, and there are more sophisticated tools available for purchase that provide a user interface and a WYSIWYG display without adding complexity to the HTML. Invest in a tool that delivers clean HTML.
  • Use CSS for styling in your documents. Use a CSS file that's external to your documents, and upload it with them. Reference the platform's reset.css and base.css files. See What are reset.css and base.css and why would I use them? below.
  • Include the <head> tag with links to the CSS. If you use reset.css (see below) and a custom css for your authored API documentation, the <head> tags in your documents would look something like the following:
    <html>
    <head>
    <title>Document Title</title>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
    <link rel="stylesheet" type="text/css" href="/resources/style/reset.css" />
    <link rel="stylesheet" type="text/css" href="/resources/style/base.css" />
    <link rel="stylesheet" type="text/css" href="customapidoc.css" />
    </head>
    
    <body>
    <p>{Your file content goes here}</p>
    </body>
    
    </html>
    
  • Include an appropriate page title tag (<title>) within the <head> tag in each file. Although the page title doesn’t show up when the page is viewed in the platform, it’s picked up by the Search feature and displayed with the search results. For example:
    <title>XXX API | Page Title</title>
  • The main heading for any documentation page is <h2>. Use of <h1> is reserved by the platform; <h2> is the top heading level for API docs.
  • If you need to make sure your content displays correctly for users of Internet Explorer version 9 or earlier, add the following three lines below the stylesheet links:
    <!--[if lte IE 9]>
    <link rel="stylesheet" href="/resources/style/ie.css">
    <![endif]-->

    For more information, see How do I make sure my API documentation is rendered correctly for users of Internet Explorer 9 and below?

Back to top

What are reset.css and base.css and why would I use them?

There are two reasons you might want to reference the platform reset.css and base.css stylesheets:

  1. Best practices: Reset.css resets styles to a baseline that's consistent across browsers. It's a good practice to reset styles and then define styles, so that the user experience for users reading your API doc is consistent across browsers.
  2. Document tagging: The various document tags used by the platform are defined in base.css. If you don't reference base.css, the doc tags will not work; if you don't use reset.css, they might not have a consistent appearance.
Best practices

When you're authoring your API documentation, it's a good idea to use consistent layout and styles so help ensure a good user experience.

You'll probably want to define your own styles. You can do that in a cascading style sheet (CSS) that's external to your files, and upload the CSS with your files, making sure that the relative location of the CSS is valid for the uploaded files. For example, you could store it in the same folder as the authored API doc content, or in a subfolder.

You can also reference the stylesheets already available on the platform. The platform's reset.css resets all styles to a consistent baseline. There are inconsistencies in the way that different browsers interpret basic styles; resetting to a consistent baseline, and building from there, helps ensure a consistent user experience across different browsers.

A second css file, base.css, adds some basic values, such as paragraph spacing and heading styles, as well as added functionality for platform documentation pages.

When you reference reset.css, some default styles such as the bulleted and numbered styles are also reset. If your documents include these elements, if you reference reset.css you'll need to define them in your API document CSS.

If you reference reset.css and your own custom css in your document files, the <head> tag of your files might look something like the below:

<head>
<title>Document Title</title>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<link rel="stylesheet" type="text/css" href="/resources/style/reset.css" />
<link rel="stylesheet" type="text/css" href="/resources/style/base.css" />
<link rel="stylesheet" type="text/css" href="customapidoc.css" />
</head>

If you use reset.css, you'll probably want to define basic styles in your own custom css. For example, your definitions for your ol (ordered list, numbered) and ul (unordered list, bulleted) might look something like the example below:

ul {
    list-style: disc outside none;
}
ol {
    list-style: decimal outside none;
}

ul, ul li, ol, ol li {
    margin-left: 13px;
    padding-left: 8px;
}

If you need to add compatibility for users of IE9 and below, you can include a conditional comment to an additional stylesheet. For details and an example, see How do I make sure my API documentation is rendered correctly for users of Internet Explorer 9 and below?

You can also reference an example API doc CSS file.

Doc tagging

The platform offers several tags that you can use to add functionality to your content; for example:

These tags rely on there being valid links to reset.css and base.css within the <head> tag of the HTML file. If base.css is not there, the tags will not work; if reset.css is not there, they might work but not look right. Both need to be there, with reset.css being listed first.

For more information on the range of tags available and how to use them in your API documentation, see API Documentation Maintenance.

Back to top

Does the platform require that HTML files be saved in a specific code format?

Yes, all HTML files must be saved in UNIX code format. This requirement is to ensure optimum compatibility across operating systems.

One method you can use to verify if your files have the correct format is to select View > Document Properties in TextPad. If the "Code set" is UTF-8, and "File type" is UNIX, then the code format your file is saved as is correct.

Note that you must also add the following meta data tag in your <head> tag to indicate that the file code set is UTF-8:

<meta http-equiv="Content-Type" content="text/html; charset=utf-8">

Back to top

API Documentation:

What API documentation publishing options does the platform provide?

After adding an API, you can add documentation for your API in the API > Documentation section using one or more of the following methods:

  • HTML—You can upload HTML documentation and associated support files (for example, graphics) using the File Explorer.
  • Methods—You can add documentation for RESTful services using the Swagger UI add-on that is integrated into the API > Documentation section. When you add a RESTful service using the Add a New API Wizard, the system adds the methods/operations defined in the API to a pre-defined system template composed of Swagger HTML, JavaScript, and css assets. You can then add your documentation content and configure what aspects of the API documentation you would like to show or hide based on the state of your current API.
  • Reference—If you already have API documentation developed and published to a website, you can create and upload a custom topic that links to the reference documentation.

Back to top

What document styles can I use for API documentation?

API documentation content should be defined using standard HTML and CSS files. In choosing styles, make sure you’re aware of any corporate or team guidelines, and be consistent across your file set so that users see the same styles and typographical conventions as they read your content.

Back to top

Can I add other types of content to my API documentation?

As well as formatted HTML for your content, and CSS files to control the visual display, you can upload some other types of content and link to them from your HTML files. For example, you can use the following:

  • Images: Upload any image files supported by browsers, such as JPG and PNG, and put them in the same folder as your HTML files, or in a subfolder.
  • Flash objects: Upload SWF files and place them in your HTML files or set them up as external links to be viewed in a separate browser window. For example, here’s a code sample that illustrates how to link a training video done in Flash:
    <a href="filename.swf" target="_blank">Training video</a> 

    The extra property after the filename, target="_blank", tells the browser to open the file in a new window instead of displaying the content in the current window (the platform UI).

  • ZIP files: These are particularly useful if you’re offering an SDK, or if you want to offer your API documentation as a download as well as making it available in the platform. You can upload a ZIP file via the File Explorer and then link to it from an HTML page. Be sure to use the Upload a File option; if you choose Upload a Zip Archive, the file is automatically unzipped when you upload it.
  • PDF files: Upload PDF files and link to them from your HTML files. Note: When you link to a PDF file, be sure to specify a target window of “new window” (target=_blank).

Back to top

How do I edit HTML page content for API documentation?

The platform supports content pages written in HTML. You must create your API and legal documents in an external HTML authoring tool and upload the documentation using File Explorer.

Back to top

API documentation and legal content in the platform can be uploaded and managed by API Admins and Business Admins.

If you are using Simple Dev theme, the API documentation must be uploaded by a Site Admin to a special folder in the Content folder structure, using The Administration menu in Default Theme/Hermosa Theme.

Back to top

To organize your API and legal documentation files:
  1. In the installation directory of the platform tenant, a /documents and /legal directory are automatically created as part of the adding the API using the Add a New API Wizard. These directories can be viewed when you launch File Explorer in the API > Documentation or API > Agreements sections of the platform.
  2. The path of the /documents and /legal folder displayed in the File Explorer includes an API ID that is assigned when the API is added to the platform. The /documents path is /content/api/{APIID}.{TenantID}/documents. The /legal path is /content/api{APIID}.{TenantID}/legal.
  3. Inside the /documents directory, create a style sheet directory (/css) to store any custom API documentation style sheets. This style sheet must work in conjunction with the document.css style sheet (located at {protocol}://{hostname}:{port}/style>/document.css).
  4. You can also create an assets directory (/assets) in the /documents directory to store image files that might be included in your documentation.
  5. Download the platform style sheet, document.css, from the {protocol}://{hostname}:{port}/style/document.css directory. A sample API documentation style sheet, apidocsample.css, can also be found here. This style sheet can be used on your local machine to develop your documentation. Click here for a doc sample that illustrates use of the apidocsample.css style sheet.
  6. Copy any custom style sheets to the /documents/css directory where you will be storing your API documentation.
  7. If you would like to upload single documentation files using File Explorer, see How do I upload my API documentation?
  8. If you would like to upload your documentation using a ZIP file, see How do I upload my API documentation in a ZIP file?
  9. Here is an example of what the /documents directory looks when you load File Explorer for the first time after creating an API:

    File Explorer for API docs

  10. If you would like to upload your documentation using a ZIP file, see How do I upload my API legal agreements?

Back to top

How do I upload my API documentation in a ZIP file?

You can upload a ZIP file that contains your API documentation using File Explorer.

To upload a ZIP file using File Explorer:
  1. Navigate to API > Documentation.
  2. Click the File Explorer icon (upper-left corner of the right pane).
  3. In File Explorer, click Upload a Zip Archive.
  4. In the File Upload box, navigate to the location of the ZIP archive file you want to upload. Choose the file, and then click Open. The ZIP file loads and expands into the /documents folder.

Back to top

You can include links to your own external website, or any other external site, in your developer portal documentation or API documentation.

Remember to use the "target="_blank" attribute on the link so that the external site opens in a new window rather than replacing the platform user interface. Refer to the examples below.

Link to an API website:

<p>For full information and API documentation, please visit the 
<a href="http://acmepaymentscorp.com/docs/index.htm" target="_blank">ACME Payments API main page</a>.</p> 

Link to the specification for a standard:

<p>For more information about OAuth 2.0, refer to the 
<a href="http://oauth.net/2" target="_blank">OAuth 2.0 specification</a>.</p> 

To upload your reference file see: How do I upload my API documentation?

Back to top

What style sheets do I use for my HTML API documentation?

If you want to reference platform styles in your HTML API documentation, you can use the lines below in the <head> tag of your API documentation files to reference the platform CSS files:

<link rel="stylesheet" type="text/css" href="/resources/style/reset.css"/>
<link rel="stylesheet" type="text/css" href="/resources/style/base.css"/>

If you want to use custom styles, you can create or upload a CSS file for your API documentation, and reference that file in your API documentation files. You can add or edit a CSS file in the same way as you do an HTML file. Just make sure you have the correct relative link. For example, in your API documentation folder, you could create a /style subfolder and keep your CSS in there.

The API documentation folder is in this location:

  • For Hermosa Theme and Default Theme: /content/api/{APIID}/documents.
  • For Simple Dev Theme: /content/documentation. The Site Admin must upload API documentation and styles for Simple Dev. See Where do I upload API documentation for Simple Dev? (Site Admin help).

Back to top

How do I set the default API documentation page using a parameter file?

When you upload a document or artifact to the Documentation section using the File Explorer, a JSON-based TOC (table of contents) file is created (format: toc.{APIVersionID}.json; for example, toc.89be612e-cde6-4a35-944b-80d7b5401099.acmepaymentscorp.json). Information about the way you've set your documents to display on the document table of contents, under the Documentation menu item in the left menu bar, are stored in this file.

Using a file editor, you can manually update the "defaultFile":"{filename}.html" parameter of the file to set your default HTML document.

If you currently have a HTML document loaded and would like to switch back so that users see the generated documentation, you can delete this parameter and reset the default document back to Swagger.

To set the default documentation page in a toc.apiversion file:
  1. In the file system, navigate to the /documents folder of your API (API > Documentation > File Explorer).
  2. If you previously uploaded an HTML file using File Explorer, open a file editor, locate the toc.apiversionXXXXX.<productname>.json file and drag the file into the editor.
  3. Update the HTML file in the "defaultFile":"<filename>.html" parameter to the new default.
  4. If you would like to switch back to the Swagger UI, remove the "defaultFile":"<filename>.html" parameter.
  5. Save the file.
  6. Return to the platform UI and clear the cache. The selected default document will display on the API > Documentation page.

Back to top

Can I upload existing API documentation and use it in the platform?

Yes, you can upload your existing file set into the platform via File Explorer. Make sure that relative file locations in the platform are the same as in your source files so that you don’t break any links between files (if any exist). The content also needs to be organized in the required document structure. See How do I organize my API and legal agreement documentation files?

Note: You must include head and body tags that reference all the css style sheets used in your API documentation.

Back to top

How do I upload API documentation?

The API > Documentation section includes an interface that allows you to add and maintain your API documentation.

You can upload documentation using File Explorer. You can upload documentation on a file by file basis, or you can upload a ZIP file.

To upload API content via the File Explorer:
  1. Navigate to API > Documentation.
  2. Click the File Explorer icon (upper-left corner of the right pane).
  3. In File Explorer, click Upload a File.
  4. In the File Upload box, navigate to the location of the file you want to upload. Choose the file, and then click Upload. You can also upload multiple files in a ZIP file. After uploading your files, set the default page. See How do I set the default API documentation page using File Explorer? or How do I set the default API documentation page using a parameter file?

Back to top

To update API and legal agreement documentation that you've added to the platform, you must upload the new file using File Explorer. See How do I upload my API documentation? or How do I upload my API legal agreements? for details.

Back to top

How do I test updated API documentation?

When you add or change API documentation, it’s a good idea to preview it in the browser to make sure it looks correct and no symbol characters are displaying. For example, if you have more than one space separating a word, the additional space may be displayed as a symbol character in some browsers.

When you save the content, it’s displayed for you in your own browser window. However, another user reading API documentation might use a different browser. Since there are differences between browser defaults that might affect the visual display, it’s a good idea to check how your content looks in the most popular browsers.

Simply copy and paste the URL. Although you need to be signed in to edit the content, no login is required for viewing most content pages.

It’s a good idea to make sure your content changes look OK in Internet Explorer, Firefox, and Google Chrome.

Back to top

How do I configure my API documentation so it's searchable in the platform?

If you would like your documentation to be searchable in the platform, include the <title> tag (for example, <title>Doc Name</title>) at the top of your HTML file, within the <head> tag.

The example below shows the structure and sequence.

Note: this example uses reset.css to reset styles. For more information, see What are reset.css and base.css and why would I use them?

<html>

<head>
  <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
  <title>Searchable Text</title>
  <link rel="stylesheet" type="text/css" href="/resources/style/reset.css"/> 
  <link rel="stylesheet" type="text/css" href="/resources/style/base.css"/>
  <link rel="stylesheet" type="text/css" href="customapidoc.css" />

  <!--[if lte IE 9]>
  <link rel="stylesheet" href="/resources/style/ie.css">
  <![endif]-->

</head>
<body>
<h2>Document Heading</h2>
<p>Document Content</p>
</body>
</html>

Back to top

Linking in API Documentation:

Use the standard # coding as shown below.

Coding of the link:

<p>For more information, see <a href="#section_2">Section 2</a>.</p>

Coding of the destination content:

<a name="section_2"></a><h4>Section 2</h4>

Note: coding for this type of link is the same in Simple Dev theme.

Back to top

Use a standard <a href> link with the filename, as shown below.

For more information about the ACME Payments API, see 
<a href="index_pmt_api.htm">ACME Payments API: Overview</a>.</p>

Back to top

Use a standard <a href> link with the relative path and the filename, as shown below.

<p>For more information about security with the ACME Payments API, see 
<a href="api_payments/acmepaymentsapi_security.htm">Security</a>.</p>

Back to top

Use a standard <a href> link with the relative path and the filename, as shown below.

<p>For an overview of the ACME Payments API, see 
<a href="../index_pmt_api.htm">ACME Payments API: Overview</a>.</p>

Back to top

Normally, when coding a relative link to another file, you must include the full filename, including extension, and take into account folder names that you might need to reference in going up or down the folder structure from one folder to another, as in the examples shown above.

When coding a link to a platform user interface page or main platform content page, you don't need to do that. You can code an absolute link using a special class that substitutes the path.

Note: You can use this approach to link to a platform page from:

  • API documentation pages
  • Any other HTML pages on the platform, such as help pages

You'll need to do these things:

  1. Reference the page's unique name. Use the part of the page URL that's after the # sign. For example:
    • Page URL: {protocol}//{hostname}/{TenantID}/#/home/apis
    • Link reference: #/home/apis
  2. Apply this class on the link: soa-control-cm-route-link.

Below are the URLs for some platform content pages you might want to link to:

  • {hostname}/#/home/support (main Support page).
  • {hostname}/#/home/apis (My APIs list)
  • {hostname}/#/home/apps (My Apps list)

For example, let's say you want to link from the API documentation to the My APIs list. All you need to do is reference the unique name, help, as follows:

<p>Go to the <a class="soa-control-cm-route-link" href="#/home/apis">My APIs list (Default Theme/Hermosa Theme)</a>,
and choose the API from the list.</p>

Back to top

Let's say you want to link from your API documentation main index page to the Markdown example file that's part of the developer portal help. This file resides in a subfolder.

First, access the file in the portal to get the URL. You'll see that the URL is:

{protocol}{hostname}/{TenandID}/#/home/learnmore/assets/markdown.htm

To link to this file from your API documentation page, you'll need to complete these actions:

  1. Reference the page's unique name in the link. Use the part of the page URL that's after the # sign. For example:
    • Page URL:
      {protocol}//{hostname}/{TenantID}/#/home/learnmore/assets/markdown.htm
    • Link reference:
      #/home/learnmore/assets/markdown.htm
  2. Apply this class on the link: soa-control-cm-route-link.

In your file, the link looks like this:

<a class="soa-control-cm-route-link" href="#/home/learnmore/assets/markdown.htm">Link to the Markdown sample file</a>

To users, the link looks like this:

Link to the platform's Markdown sample file

In the <head> tag of your file, the script file is referenced like this (line break added for readability):

<script language="javascript" src="/ui/apps/atmosphere/123/resources/console/SOA/console/common/tag_lib/dist/tag_lib.min.js" 
type="text/javascript"></script>

Back to top

When coding a link to an external site, document, or other file, first test the link yourself in the browser. Include target="_blank" as shown below so that the site or document opens in a new browser tab or window rather than replacing the existing one.

<p>For more information, visit <a href="http://acmepaymentscorp.com/api" target="_blank">http://acmepaymentscorp.com/api</a>.</p> 

Back to top

How do I link to another API documentation file in the API documentation folder in Default Theme/Hermosa Theme?

If you have multiple documentation files in the documentation folder and want to link directly to one of them without using a relative link, you can just use the standard coding to reference another file in the same folder, as shown below:

<a href="another_api_doc_file.htm">Another API Doc File</a>

Back to top

When do I need to reference the tag_lib.min.js file?

The platform includes a JavaScript file, tag_lib.min.js, that you can link to in the <head> tag of your HTML files to support the use of the following tags in your API documentation or other content files:

You do not need to reference this file when using the soa-control-cm-route-link class used in linking to platform pages.

Back to top

How do I reference the tag_lib.min.js file?

If you are using one or more of the additional tags that rely on the JavaScript file, tag_lib.min.js (see When do I need to reference the tag_lib.min.js file? above), you'll need to include a link to this file.

In the <head> tag of your HTML file, reference the script file like this (line break added for readability):

<script language="javascript" src="/ui/apps/atmosphere/123/resources/console/SOA/console/common/tag_lib/dist/tag_lib.min.js" 
type="text/javascript"></script>

The entire <head> tag might look something like the below:

<html lang="en" xmlns:soa="http://soa.com">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>
    <meta http-equiv="X-UA-Compatible" content="IE=edge"/>

<!-- The css files below are needed for the inline testing feature to be displayed correctly -->
    <link rel="stylesheet" type="text/css" href="/resources/style/reset.css"/> 
    <link rel="stylesheet" type="text/css" href="/resources/style/base.css"/>

    <!--[if lte IE 9]>
    <link rel="stylesheet" href="/resources/style/ie.css">
    <![endif]-->

<!-- The script files below are needed for the inline testing feature to work correctly -->
    <script language="javascript" src="config.js" type="text/javascript"></script>
    <script language="javascript" src="/ui/apps/atmosphere/123/resources/console/SOA/console/common/tag_lib/dist/tag_lib.min.js"type="text/javascript"></script>

Notes:

Back to top

Using File Explorer:

What is File Explorer and what functionality does it offer?

File Explorer is a simple file management tool that allows you to upload documentation source files in these parts of the developer portal:

  • API > Documentation: click the icon in the upper left-hand corner of the right pane.
  • API > Documentation: click Manage Files.

File Explorer includes the following functionality:

This File Manager feature... Allows you to...
Go up a Directory Navigate one level up the directory tree. By default, API documentation is stored in the \documents default directory. If you are creating a folder structure, make it below, not above. All documentation for a specific API should reside in the applicable \documents folder or folders below it.
New Directory Create a new subdirectory in the current directory.
Upload a File Upload a single file; for example, HTML, .swg, and associated documentation support files such as images, one file at a time.
Upload a Zip Archive Upload a ZIP archive into the \documents folder.
Download Directory Download the current directory, and all files and folders below it that you are authorized to access, into one ZIP file. You have the option to save or open the file.
Show in TOC Display a file in the left-hand navigation underneath the Documentation menu.
Default Identify the default file that will load when the user chooses the Documentation menu.
Rename Rename a file. When selected a File Name popup displays where you enter the file to be renamed.
View Direct View the current file via a URL address.
Set Display Name Configure the name that will display in the Documentation section if the Show in Toc option is selected. When selected, a File Namee popup displays where you enter the file to be renamed.
Delete Delete a file.

Back to top

How do I add a file to the API documentation table of contents?

To add a file to the documentation table of contents:
  1. Navigate to API > Documentation.
  2. Click the File Explorer icon (upper-left corner of the right pane).
  3. In File Explorer, click the box for the file, under Show in TOC. The filename displays in the Documentation table of contents. Note that this does not make this file the default viewed when users click Documentation, it just adds it to the left menu.

    File Explorer: Show in TOC

You can take additional steps to control accessibility of the API documentation:

Back to top

How do I set the default API documentation page using File Explorer?

To set the default API documentation page that is displayed when users click API > Documentation:

Note: First, upload the page that you want to display as the default. For instructions, see How do I upload API documentation?

  1. Navigate to API > Documentation.
  2. Click the File Explorer icon (upper-left corner of the right pane).
  3. In File Explorer, click the Default radio button. The selected document will automatically be displayed when users click API > Documentation.

    File Explorer: Setting the Default

Back to top

How do I set the file display name in the API documentation table of contents?

To set the display name of a file in the API documentation table of contents:
  1. Navigate to API > Documentation.
  2. Click the File Explorer icon (upper-left corner of the right pane).
  3. In File Explorer, click Set Display Name. The Display Name dialog box displays. Enter the name you would like to display in the table of contents for this file and click OK. The name of the file changes in the table of contents, as shown below.

    File Explorer: Setting the Display Name

Back to top

How do I rename a file in File Explorer?

To rename a documentation source file:
  1. Navigate to API > Documentation.
  2. Click the File Explorer icon (upper-left corner of the right pane).
  3. In File Explorer, click the Rename icon.

    File Explorer: Rename

  4. The File Name dialog box displays. Enter the new filename and click OK. Be sure to preserve the file extension, or rename to a valid extension for the file type. The filename changes in the File Explorer display.

Note: When renaming a file, it's important to make sure the new name includes a valid file extension that's correct for the file format; for example, index.html or index.htm.

Back to top

How do I view a file in File Explorer?

To view a documentation source file:
  1. Navigate to API > Documentation.
  2. Click the File Explorer icon (upper-left corner of the right pane).
  3. In File Explorer, click the View Direct icon. The selected document views in the browser.

    File Explorer: View Direct

Back to top

How do I delete a file using File Explorer?

To delete a document source file:
  1. Navigate to API > Documentation.
  2. Click the File Explorer icon (upper-left corner of the right pane).
  3. In File Explorer, click the Delete icon.

    File Explorer: Delete

  4. At the confirmation prompt, click OK.

Back to top

Using Swagger:

What is Swagger and how does it work?

Swagger (http://swagger.io) is a specification and complete framework implementation for describing, producing, consuming, and visualizing RESTful web services. It produces dynamically generated documentation that includes methods, parameters and models. The platform includes an implementation of Swagger that works in conjunction with the Add a New API Wizard.

When you define an API, the structure is dynamically generated and added to a predefined Swagger template. The documentation-ready structure is available in the API > Documentation section where you add a title, description, implementation notes, and parameter information.

The documentation content is stored in a resources.swg file. Using the File Explorer you can add this file to your table of contents to make it the default display document when a user clicks the API > Documentation menu. You can also add the Swagger document URL to your HTML documentation.

Back to top

What are the Swagger controls and how do I edit page content?

The Swagger documentation includes a series of page controls for displaying and navigating through the method documentation as follows:

Swagger Controls:

  • Show / Hide—A toggle that expands or collapses the API methods.
  • List Operations—Displays the API operations.
  • Expand Operations—Displays the Implementation Notes and Parameter section of the operations.
  • Raw—Displays the JSON code that comprises the resources.swg file.

Editing Options:

You can add / edit the following areas in Swagger documentation. First navigate to the API > Documentation page that includes the Swagger and perform the desired step.

To add a page title:
  1. Click into the "Click here to add a title" text box and specify your documentation title.
  2. To save the title, click outside the text box.
To add a description:
  1. Click into the "Click here to add a title" text box and specify your documentation title.
  2. To save the title, click outside the text box.
To add implementation notes to an API operation:
  1. Go to a method and select List Operations.
  2. Select the operation you would like to add implementation notes to and click Expand Operations.
  3. Double click under the "Implementation Notes" label, select "Double-click to add Notes." A text box displays.
  4. Enter your data and click outside the text box to save.
To add a parameter description to an API operation:
  1. Go to a method and select List Operations.
  2. Select the operation you would like to add implementation notes to and click Expand Operations.
  3. In the Parameters section, select "Double-click to parameter description." A text box displays.
  4. Enter your data and click outside the text box to save.

Back to top

What style sheets do I use for my Swagger documentation?

The developer portal provides a pre-defined Swagger style sheet that is internal to the product and is applied to all dynamically generated Swagger documentation structures.

Back to top

Can I mix Swagger and HTML files in my API documentation?

The developer platform automatically generates the Swagger documentation and pre-fills it with information from the runtime service definition. It parses the definition file and generates a Swagger document with no adornments (descriptions and so forth) that is technically accurate for each resource and verb.

At that point the API Admin can annotate the Swagger documentation in two ways:

  • Directly in the Swagger implementation in the browser by double-clicking on a text field and typing, which generates a properties file.
  • By uploading a properties file created offline, or downloaded and then edited offline.

Whether the properties file is uploaded or auto-generated, the developer portal merges the properties file with the generated Swagger documentation to produce the resulting document that is displayed to the user (rendered by the Swagger UI JavaScript).

By default, when you add an HTML file to the documents list in the folder for your API documentation, the developer portal defaults to using HTML documentation only, rather than a mix of HTML docs and Swagger docs.

For instructions to use a mix of Swagger and HTML files, see Combined Authored and Generated API Documentation.

It's best to modify the display names; otherwise, the display name is the filename, including extension.

Note: If you have a Swagger properties file in the documentation folder, the developer portal merges the Swagger properties with the generated Swagger template.

For information about uploading API documentation files, see How do I upload API documentation?

Back to top

The APIs > Agreements section provides functionality that allows you to upload and manage legal agreements that pertain to each API. An API may require one or more legal agreements. Legal agreements with an approved status display in the API Access function. A user must accept the terms of the legal agreements to gain access to API functionality.

  • Legal agreements must be in HTML format.
  • A legal agreement should follow the style conventions defined in the platform default style sheet (document.css) located at http://tenanthost:port/content/style/document.css.
  • Legal agreements can be any unique filename.
  • All legal agreement files must be uploaded to the \legal folder.
To upload the API legal agreement file via the File Explorer:
  1. Navigate to My APIs > API > Agreements.
  2. Click Manage Files.
  3. In File Explorer, click Upload a File.
  4. In the File to Upload dialog box, click Browse to navigate to the location of the file you want to upload. Choose the file, and then click Open.
  5. Click the Publish check box to add the document name to the Agreements list accessible via Manage Agreements.
  6. Click outside the File Explorer to exit.

Back to top

API legal agreements use the platform default style sheets. Active legal agreements display in the API Access Wizard when a user requests access to your API. To ensure that your legal agreement displays properly in this wizard, download the legal agreement sample file and use it as a template to structure your legal agreement HTML.

Click here to download a sample legal agreement file.

Back to top