Content Development Guidelines

This section provides guidelines that API providers can use to manage API content such as API documentation and legal agreements.

Note: For information about tagging API documentation and other documentation so that it's visible only to viewers with a certain role or permission level, see API Documentation Maintenance.

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 > Documents section.

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.

Bear in mind:

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.
Include the <head> tag with links to your style sheets. For example, the default online help for the developer portal uses the default site style sheet (base.css) and document.css style sheet. Document.css includes all the custom styles for the documentation and takes certain elements (for example, spacing) from the base.css. Using these style sheet examples, your <head> tags would look something like the following:
```
<html>
<head>
<title>Document Title</title>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<link href="../../../../resources/style/reset.css" rel="stylesheet" type="text/css" />
<link href="../../../../resources/style/base.css" rel="stylesheet" type="text/css" />
<link href="../../style/document.css" rel="stylesheet" type="text/css" />
</head>

<body>
HTML Content
</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.

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">

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 > Documents 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 > Documents 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.

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.

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).

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.

Who can edit API and Legal Agreement content?

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 Default Theme's Administration menu..

How do I organize my API and legal agreement documentation files?

To organize your API and legal documentation files:

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 > Documents or API > Legal sections of the platform.
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.
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).
You can also create an assets directory (/assets) in the /documents directory to store image files that might be included in your documentation.
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.
Copy any custom style sheets to the /documents/css directory where you will be storing your API documentation.
If you would like to upload single documentation files using File Explorer, see How do I upload my API documentation?
If you would like to upload your documentation using a ZIP file, see How do I upload my API documentation in a ZIP file?
Here is an example of what the /documents directory looks when you load File Explorer for the first time after creating an API:
If you would like to upload your documentation using a ZIP file, see How do I upload my API legal agreements?

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:

Navigate to API > API Name > Documents.
Click the File Explorer icon (upper-left corner of the right pane).
In File Explorer, click Upload a Zip Archive.
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.

Can I link to an external site?

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?

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

You might find that the default styles in the platform work fine for you and are all you need. If you need custom styles, you can create or upload a CSS file. You can add or edit a CSS file in the same way as you do an HTML file.

Click here to download a sample API documentation style sheet. These styles are part of the document.css style sheet located userdocs\style directory. If you would like to develop your API documentation using these styles, or choose to update these styles, make sure you update the document.css file before uploading your documentation to the site.

The following paths illustrate the location of the \style directory relative to the \learnmore directory. This is where the current document.css file is stored. Based on your requirements you can choose to store your \css in a different location (for example, in the same directory as your files or in a \css folder in your \Documents directory).

\userdocs\home\learnmore
\userdocs\style

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

When you upload a document or artifact to the API > Documents 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 Documents menu item in the left menubar, 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:

In the file system, navigate to the Documents folder of your API.
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.
Update the HTML file in the "defaultFile":"<filename>.html" parameter to the new default.
If you would like to switch back to the Swagger UI, remove the "defaultFile":"<filename>.html" parameter.
Save the file.
Return to the platform UI and clear the cache. The selected default document will display on the API > Documents page.

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.

How do I upload API documentation?

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

Documentation must be in HTML format.
It should follow the style conventions defined in the platform default style sheet (document.css) located in the apidocs\styles\ folder, and your custom API style sheet (if used) located in your {apiname}\documents\css directory.
You can configure any document to be the top-level/intro page that displays when you click API > Documents. 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?.
All documentation files must be uploaded to the \documents folder that is auto-generated when an API is created using the Add a New API Wizard.
If you would like specific files to display in the Documents left navigation, you can click the Show in TOC checkbox in the File Explorer. See How do I set the file display name in the API documentation table of contents?

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:

Navigate to API > API Name > Documents.
Click the File Explorer icon (upper-left corner of the right pane).
In File Explorer, click Upload a File.
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?

How do I update API and legal agreement documentation I've added to the platform?

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.

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.

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.

<html>

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

Linking in API Documentation:

How do I link to another location in the same document in Default Theme?

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 Default Theme and Simple Dev theme.

How do I link to a content file in the same folder in Default Theme?

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>

How do I link to an API content file in a subfolder in Default Theme?

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>

How do I link to a content file in a parent folder in Default Theme?

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>

How do I link to a platform content page in Default Theme?

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:

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
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 leading to the online help)
{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)</a>,
and choose the API from the list.</p>

Here is another example.

Let's say you want to link from your API documentation main index page to the Glossary of Terms in the developer portal help.

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

{protocol}{hostname}/{TenandID}/#/home/learnmore?basics_glossary.htm

Again, you'll need to complete these actions:

Reference the page's unique name in the link.:
- Page URL: {protocol}//{hostname}/{TenantID}/#/home/learnmore?basics_glossary.htm
- Link reference: #/home/learnmore?basics_glossary.htm
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?basics_glossary.htm">Link to the platform's Glossary of Terms</a>

To users, the link looks like this:

Link to the platform's Glossary of Terms

How do I link to a platform content page in a platform subfolder in Default Theme?

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:

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
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>

How do I link to an external site or document in Default Theme?

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>

How do I link to another API documentation file in the API documentation folder in Default 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>

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:

soa:testclient (used for including inline Test Client in your authoredAPI documentation: see Test Client in API Documentation)
soa:generatedoc (used for including inline generated API documentation in your authored API documentation: see Combined Authored and Generated API Documentation)

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

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"/>

<!-- 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>

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 to various parts of the platform UI:

In the API > Documents section you load File Explorer by clicking the icon in the upper left-hand corner of the screen.
In the Legal section, you load File Explorer by clicking Manage Files.

File Explorer includes the following functionality:

File Manager Features	Description
Go up a Directory	Allows you to 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	Allows you to create a new subdirectory in the current directory.
Upload a File	Allows you to 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	Allows you to upload a ZIP archive into the \Documents folder.
Download Directory	Allows you to 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	A checkbox that allows you to display a file in the left-hand navigation underneath the Documents menu.
Default	A radio button that allows you to identify the default file that will load when Documents menu is selected.
Rename	Allows you to rename a file. When selected a File Name popup displays where you enter the file to be renamed.
View Direct	Allows you to view the current file via a URL address.
Set Display Name	Allows you to configure the name that will display in the Documents section if the Show in Toc option is selected. When selected, a File Name popup displays where you enter the file to be renamed.
Delete	Allows you to delete a file by clicking "x."

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

To add a file to the documentation table of contents:

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

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

To set the default, see How do I set the default API documentation page using File Explorer?
To change the display name of the file, see How do I set the file display name in the API documentation table of contents?

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 > Documents:

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

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

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:

Navigate to API > API Name > Documents.
Click the File Explorer icon (upper-left corner of the right pane).
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.

How do I rename a file in File Explorer?

To rename a documentation source file:

Navigate to API > API Name > Documents.
Click the File Explorer icon (upper-left corner of the right pane).
In File Explorer, click the Rename icon.
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.

How do I view a file in File Explorer?

To view a documentation source file:

Navigate to API > API Name > Documents.
Click the File Explorer icon (upper-left corner of the right pane).
In File Explorer, click the View Direct icon. The selected document views in the browser.

How do I delete a file using File Explorer?

To delete a document source file:

Navigate to API > API Name > Documents.
Click the File Explorer icon (upper-left corner of the right pane).
In File Explorer, click the Delete icon.
At the confirmation prompt, click OK.

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 > Documents 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 > Documents menu. You can also add the Swagger document URL to your HTML documentation.

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 API > Documents page that includes the Swagger and perform the desired step.

To add a page title:

Click into the "Click here to add a title" text box and specify your documentation title.
To save the title, click outside the text box.

To add a description:

Click into the "Click here to add a title" text box and specify your documentation title.
To save the title, click outside the text box.

To add implementation notes to an API operation:

Go to a method and select List Operations.
Select the operation you would like to add implementation notes to and click Expand Operations.
Double click under the "Implementation Notes" label, select "Double-click to add Notes." A text box displays.
Enter your data and click outside the text box to save.

To add a parameter description to an API operation:

Go to a method and select List Operations.
Select the operation you would like to add implementation notes to and click Expand Operations.
In the Parameters section, select "Double-click to parameter description." A text box displays.
Enter your data and click outside the text box to save.

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.

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?

Legal Agreements:

How do I upload my API legal agreements?

The APIs > Legal 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:

Navigate to API > API Name > Legal.
Click Manage Files.
In File Explorer, click Upload a File.
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.
Click the Publish checkbox to add the document name to the Agreements list accessible via Manage Agreements.
Click outside the File Explorer to exit.

What style sheets do I use for my API legal agreements?

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.