Documenting an API

Before You Begin

This 10-minute tutorial shows you how to add documentation to an API in Oracle API Platform Cloud Service and use an Apiary API specification as the documentation for the API.

Background

When you publish an API in the Oracle API Platform Cloud Service Developer Portal, adding documentation is critical for application developers to understand what the API does and how it works.

You can create and publish documentation for an existing Apiary API. To accomplish this, you must link the existing API to the documentation in Apiary. You can then publish the API so that application developers know the purpose, features, and usage of the API. 

What Do You Need?

• Access to an Oracle API Platform Cloud Service instance, with the application developer role.
• An Apiary account.
• An existing API in Apiary that you own. For this tutorial, you can use the Warranty Claim API as an example.
• An existing API in Oracle API Platform Cloud Service.

Access the API in Management Portal

1. Sign in to the Oracle API Platform Cloud Service Management Portal by entering a URL in the following format:

   https://instance-identityDomain.apiplatform.ocp.oraclecloud.com/apiplatform

   For example, https://apidemo-paasproducm.apiplatform.ocp.oraclecloud.com/apiplatform

2. On the APIs page, select the Warranty Claim API from the list. Alternatively, in the Search By Name field, enter Warranty Claim, and then select the Warranty Claim API. 

Link Apiary and API Actions to the API

1. On the Specification page, click Apiary.

   

2. If prompted, sign in to Apiary Portal.
3. From the list of API projects, select the Warranty Claim project.
4. Select the Use as API Documentation check box.
5. Click Connect to link the Apiary Warranty Claim project as the specification and documentation for the API.

   

6. To verify that the Apiary project data is downloaded, make sure that a link with File: Warranty Claim appears under the Apiary button, and the API Actions are defined.

   

7. Click Save.

Add Text for the Developer Portal API Overview

1. On the API details page, select the Publication tab.
2. In the Developer Portal API Overview section, click HTML.

   

3. Click the Text tab.
4. Enter a short, one-sentence description for the API.

   

5. Click OK.

Configure the API Portal URL

1. In the Enter the Portal name field, located under API Portal URL, enter the URL of the Oracle API Platform Cloud Service Developer Portal.

   

2. Click the tick mark .
3. Click Save.

Publish the API to the Developer Portal

1. Click Preview, to view the documentation.
2. After you verify the API documentation, click Publish to Portal.

   Note: If you have already published to the portal and later make changes to the documentation or overview, then click Republish.

   

Open the Developer Portal

1. On the APIs page, select Warranty Claim.
2. Click the link under API Portal URL, to see the documentation in the Oracle API Platform Cloud Service Developer Portal.

   

3. Verify that the API opens on the Oracle API Platform Cloud - Developer Portal page.

   

Want to Learn More?

• Manage APIs