Content Development Guidelines


This section provides guidelines that API Providers can use to manage API and legal agreement documentation content.

Publishing

What API documentation publishing options does SOA Software Open provide?

What is File Explorer and what functionality does it offer?

What is Swagger and how does it work?

Editing

Who can edit API and legal agreement content in SOA Software Open?

What document management tasks can I perform in SOA Software Open?

How do I edit HTML page content?

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

How do I set the default documentation page?

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

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

How do I rename a file in File Explorer?

How do I view a file in File Explorer?

How do I delete a file using File Explorer?

Styles

What are the general HTML coding guidelines?

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

What style sheets do I use for my Swagger documentation?

What style sheets do I use for my legal agreements?

What document styles can I use?

Can I add other types of content?

Content Organization

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

How do I zip my documentation files?

Can I link to API documentation on a different site?

File Upload

How do I upload my API documentation?

Can I upload existing API documentation and use it in SOA Software Open?

How do I upload my legal agreements?

Testing

How do I test updated content?

Updating

How do I update API and legal agreement documentation I've added to SOA Software Open?

Publishing

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 SOA Software Open UI:

File Explorer includes the following functionality:

File Manager Features Description
Go up a Directory Allows you to navigate the \documents default directory.
New File  
Upload a File Allows you to upload a single HTML, .swg, and associated documentation support files (e.g., graphics).
Upload a Zip Archive Allows you to upload a zip archive into the \Documents folder.
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."

Back to top

What API documentation options does SOA Software Open 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:

Back to top

What is Swagger and how does it work?

Swagger by Wordnic (http://swagger.wordnik.com/) 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. SOA Software Open 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 make it the default display document when you click the API > Documents menu. You can also add the Swagger document URL to your HTML documentation.

Back to top

Editing

Who can edit API and Legal content in SOA Software Open?

API documentation and legal content in SOA Software Open can be uploaded and managed by Site Administrators, API Providers, and designated Administrators of an API.

Back to top

What document management tasks can I perform in SOA Software Open?

Within SOA Software Open, editing of API and Legal Agreement content is limited to:

Development of document content must be performed outside of the SOA Software Open product, with the exception of Swagger API documentation which is entered directly into the templates in the API > Documents section.

Back to top

How do I edit HTML page content?

SOA Software Open 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 the SOA Software Open File Explorer.

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:

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:

  1. Click into the "Click here to add a title" text box and specify your documentation title.
  2. To save the title, click outside of 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 of 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

How do I set the default documentation page?

To set the default document page that will load when you click API > Documents:

  1. Navigate to API > API Name > Documents.
  2. Click the File Explorer icon (in upper-left corner of the pages)
  3. In File Explorer, click the Default radio button. The selected document will automatically display first when you select the API > Documents menu.

Back to top

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

To add a file to the table of contents:

  1. Navigate to API > API Name > Documents.
  2. Click the File Explorer icon (in upper-left corner of the pages)
  3. In File Explorer, click the Show in Toc icon. The filename displays in the Documents table of contents. If you would like to change the display name of the file, see How do I set the file display name in the table of contents?

Back to top

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

To set the display name of a file in the table of contents:

  1. Navigate to API > API Name > Documents.
  2. Click the File Explorer icon (in upper-left corner of the pages)
  3. In File Explorer, click the Set Display Name icon.

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

Back to top

How do I rename a file in File Explorer?

To rename a documentation source file:

  1. Navigate to API > API Name > Documents.
  2. Click the File Explorer icon (in upper-left corner of the pages)
  3. In File Explorer, click the Rename icon.



  4. The File Name dialog box displays. Enter the new filename and click OK. The filename changes in the File Explorer display.

Back to top

How do I view a file in File Explorer?

To view a documentation source file:

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


Back to top

How do I delete a file using File Explorer?

To delete a document source file:

  1. Navigate to API > API Name > Documents.
  2. Click the File Explorer icon (in upper-left corner of the pages)
  3. In File Explorer, click the Delete icon.

    .
  4. The "Are you sure you want to delete this file?" dialog displays.


  5. Click OK to delete the document or click Cancel to exit the operation.

Back to top

Styles

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 these points:

Back to top

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

You might find that the default styles in SOA Software Open work fine for you and are all you need. If 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.

Note: If you have a custom CSS file for your documentation, make sure it’s stored in the documents/css subdirectory. You can create this directory via the File Explorer if it doesn’t already exist. Your CSS filename must not include illegal characters, but it must have the extension .CSS and be stored in the /css subfolder. Click here to download a sample API documentation style sheet.

Back to top

What style sheets do I use for my Swagger documentation?

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

What style sheets do I use for my legal agreements?

Legal agreements use the SOA Software Open default style sheets. For your testing purposes you can download the SOA Software Open style sheets at: http://tenanthost:port/resources/style/document.css

Back to top

What document styles can I use?

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?

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:

Back to top

Content Organization

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

To organize your API and legal documentation files:

  1. In the installation directory of the SOA Software Open 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 SOA Software Open.
  2. The path of the /documents and /legal folder displayed in the File Explorer includes an API ID (apixxxxx where "xxxxx" represents a number) that is assigned when the API is added to SOA Software Open. The /documents path is /content/api/apixxxxx.open/documents. The /legal path is /content/api/apixxxxx.open/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 http://tenanthost:port/resources/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 SOA Software Open style sheet, document.css, from the http://tenanthost:port/resources/style/document.css directory. A sample API documentation style sheet can be found here. These can be used on your local machine to develop your documentation. Click here for a doc sample that illustrates use of the document.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 zip my documentation files?

  9. Here is an example of what the /documents directory looks when you load File Explorer for the first time after creating an API:

  10. Here is an example of what the /legal directory looks when you load File Explorer for the first time after creating an API:

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

Back to top

How do I zip my documentation files?

You can upload a zip file that containers your documentation using the SOA Software Open File Explorer.

To upload a zip file using File Explorer:

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

Can I link to API documentation on a different site?

Yes. If you already have a website established for your API and/or your documentation, you can upload a file that includes introductory text and includes a link to your website. For example:

Example HTML:

<title>My API</title>
<p>Please go <a href="http://myapi.com/docs/reference/api/" target=”_blank”>here</a> to see the details of this API.</p>

Note: If you are linking to an external site, include target=”_blank” in the HTML file to open the external site in a new window.

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

Back to top

File Upload

How do I upload API documentation?

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

You can upload documentation using the SOA Software Open 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 > API Name > Documents.
  2. Click the File Explorer icon (in upper-left corner of the pages)
  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 Open. After uploading your files, set the default page. See How do I set the default documentation page?

Back to top

Can I upload existing API documentation and use it in SOA Software Open?

Yes, you can upload your existing file set into SOA Software Open via the 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: If you are using styles in /resources/styles/document.css, your content files should not include head and body tags. If you are using custom styles that are not uploaded to /resources/styles/document.css, you must include head and body tags that reference the style sheets used in your /css directory where your API documentation is stored.

If you would like your documentation to be searchable in SOA Software Open, include the <title> tag (e.g., <title>Doc Name</title>) at the top of your HTML file.

Back to top

How do I upload my 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 SOA Software Open API Access function. A user must accept the terms of the legal agreements to gain access to API functionality.

To upload the legal agreement file via the File Explorer:

  1. Navigate to API > API Name > Legal.
  2. Click the File Explorer icon (in the upper-left corner of the page), or click Manage Files.
  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 Open.
  5. Click the Add to TOC checkbox to add the document name to the table of contents that displays in the left navigation of the Legal menu.
  6. From the Options menu drop-down, select Set Display Name. In the "Display Name" field, configure the document name that will display in the left navigation. Click OK.
  7. Click outside of the File Explorer to exit.

Back to top

Testing

How do I test updated content?

When you add or change content, 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

Updating

How do I update API and legal agreement documentation I've added to SOA Software Open?

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

Back to top