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
- 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
- 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
- On the Specification page, click Apiary.
Description of the illustration specification.png - If prompted, sign in to Apiary Portal.
- From the list of API projects, select the Warranty Claim project.
- Select the Use as API Documentation check box.
- Click Connect to link the Apiary Warranty
Claim project as the specification and
documentation for the API.
Description of the illustration apiary-documentation.png - 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.Description of the illustration apiary-link.png - Click Save.
Add
Text for the Developer Portal API Overview
- On the API details page, select the Publication tab.
- In the Developer Portal API Overview
section, click HTML.
Description of the illustration devportal-html.png - Click the Text tab.
- Enter a short, one-sentence description for the API.
Description of the illustration devportal-html-text.png - Click OK.
Configure
the API Portal URL
- In the Enter the Portal name field,
located under API Portal URL, enter the URL
of the Oracle API Platform Cloud Service Developer Portal.
Description of the illustration developer-url.png - Click the tick mark
.
- Click Save.
Publish the API to the Developer Portal
- Click Preview, to view the documentation.
- 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.
Description of the illustration publish-portal.pn
Open
the Developer Portal
- On the APIs page, select Warranty Claim.
- Click the link under API Portal URL, to see
the documentation in the Oracle API Platform Cloud Service
Developer Portal.
Description of the illustration launch.png - Verify that the API opens on the Oracle API Platform Cloud -
Developer Portal page.
Description of the illustration api-platform-cloud.png