Updated reflecting changes discussed in blog post:
Making Scripts Work with IDCS Deployed PaaS

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 :

• https://nordicapis.com/the-easiest-ways-to-generate-api-documentation/
• https://dzone.com/articles/best-practices-in-api-documentation

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.

This is where the new utility comes into play. The utility we’ve produced will take one or more APIs or Applications and then harvest the documentation from the policies and the overall policy information and generates a markdown description of the API. If the policy has no documentation then the default policy description is used. The outcome is documentation which doesn’t give away too much information about the policy execution but will provide sufficient insight to address those other documentation points.

The utility can be retrieved from  https://github.com/mp3monster/Utils/blob/master/getDesignDoc.groovy

The following image shows the kind of output that can be generated.

To use the utility it obviously needs Groovy to be installed and available.

Parameters

The following outlines the parameters that can be used. The following parameters are mandatory:

1. Server url e.g. https://1.2.3.4/
2. Username
3. Password

The following are all optional parameters that will inform the behaviour:

• -h will result in the help info being provided
• -m <APP | API > proving either of the values APP or API tells the tool whether to match he name against an API or an application name. If this value is not provided then API is the default
• -n <partial or complete application or API name> this is used to match an API or APP name. The string provided just needs to appear somewhere in the name. If this value is not provided then all APIs will be published irrespective of the -m parameter. If the Parameter is for an APP then all APIs in that app will be documented
• -f <filename> this will define the filename to write, if more than one API matches then they all get written to this file. Otherwise the API name forms the filename
• -s <CHANGEINFO, VERSIONINFO, POLICYINFO, EXCLUDE> – this controls what information is excluded, the -s needs to be followed by one or more of these value separated by a comma (and no spaces). The first 3 exclude parts of the policy documentation. The last one tells the process if it finds the word EXCLUDE as the last word in the policy description then that policy description will be excluded from the output. So for example, if you wanted to exclude from the documentation that there is a Logging policy, then add the word into the description and the policy will be excluded from the document generated.
• -d sets the app into display all, aka verbose mode