PaaS Partner Community

Cloud, Integration
February 10, 2019

Documenting APIs on the Oracle API Platform by Phil Wilkins

Juergen Kress
PaaS & Middleware Partner Adoption

The last week or two I have been working on a new API Platform utility to add to my existing tools (see here). This tool addresses the question of generating documentation. Much as been said about API documentation and the quality of it, check out these articles :

If you look at these articles and others, there are some common themes, which are:

Document the URI / payload
Describe error handling
Describe contracts such as how many API calls
How the API is authenticated

Apiary covers the first theme to a first class standard, and you will see Apiary called out for its ability to document APIs in a lot of articles. Well written API Blueprints will cover the bulk of the second bullet. But the other points tend to fall outside of a Blueprint and fit more the API Policies and their use.

Not everyone is so commited or enjoys writing documentation. The other driver for going beyond the use of Apiary is that some organizations feel the need to have a traditional word style document to capture/define an API’s contract in detail. With the API Platform the management portal enables an API to be published into the developer portal with the Apiary definition and a markdown file for further documentation.

As you can see some of the information about the policies should be incorporated into the documentation. So how, can the gap be addressed easily. Within the policy definition is the means to provide documentation, as illustrated below. This provides an opportunity to record a more general explanation as to what and how to address that policy. Read the complete article here.

PaaS Partner Community

For regular information on Oracle PaaS become a member in the SOA & BPM Partner Community for registration please visit www.oracle.com/goto/emea/soa (OPN account required) If you need support with your account please contact the Oracle Partner Business Center.

Blog Twitter LinkedIn Facebook Wiki