Generating API Documentation for Both External and Internal Users
In this article, see how to generate documentation for both external and internal users.
Join the DZone community and get the full member experience.Join For Free
A recurring need in larger integration projects is the generation of API documentation for users belonging to different, yet related, target groups. Read on to learn how to generate Zato-based API specifications for more than one group from a single source of information.
A typical scenario is granting access to the same APIs to external and internal users - what they have in common is that all of them may want to access the same APIs yet not all of them should have access to documentation on the same level of details.
For instance, external developers should only know what a given endpoint is for and how to use it but internal ones may also be given information about its inner workings, the kind of details that external users should never learn about.
If documentation for two such groups is kept separately, it may require more maintenance effort than necessary - after all, if most of it is the same for everyone then it would make sense to keep it in one place and only add or remove details, depending on which group particular API documentation needs to be generated for.
The previous article went through the process of generating API specifications step by step - this one goes even further by adding introducing the notion of tags that drive which parts of documentation to generate or not.
Let's use one of the same services as previously — here is its basic form:
The result, when generated as Sphinx, will be like below:
Now, we would like to add some details that only internal users should have access to - this is how the docstring should be modified, assuming for a moment that there are two CRM systems in the company the usage of which depends on a particular end user's account...
...with the corresponding change in the output:
What happened above was that we applied a tag called #internal - anything that follows it is included in the output only if that very tag is requested when generating the documentation.
Note that the tag name is arbitrary, it could be any other name. Note also that there may be more than tag in a docstring, e.g. #confidential, #private or anything else.
To actually include the #internal tag, the zato apispec command needs to be told about it explicitly, as below:
If you do not give the command any tags, only the public part of the docstring, one without any tags, will be included in the resulting documentation.
To make your clear to other developers, you can also directly use the tag public in the command - this will make it easier to understand that you want to generate publicly available information and nothing else.
Wrapping It Up
This is it, you are done now; you can keep your API documentation in one place and include only the relevant parts of it depending on the context. This ensures that no matter who the recipient of your documentation is, it will be always generated from a single source, thus ensuring that all the output will stay in sync.
Opinions expressed by DZone contributors are their own.