Background
As previously mentioned I spent some time earlier this year establishing wiki solution at work to replace the cruft that is MS SharePoint. Far from surprising I ended up choosing Atlassians Confluence. Since I’m primarily working on API’s (internal and external, web and native) one of the first things I did was use the wiki to document our APIs.
PDF exports
Since using Confluence at Zystems the PDF export has been hugely improved which is a killer feature when having to email docs to people (we’re not letting API consumers into the wiki, yet). Customizing the PDF renderer with custom header, footer and front page, logos and such is fairly simple.
User macro to render service response
I then went all nuts on the user macro feature and made a few re-usable macros that look somewhat like:
{json-api:Calling some service|http://some.domain/v1/some/service?parameter=value}
This macro then produces a nice little panel with the title “Calling some service” which then contains the URL given to the macro. Beneath that it displays the result of actually invoking the service. Now, rendering one API documentation page thus yields a few (1 – 5) different service calls but this is highly cacheable.
What about PUT/POST/DELETE endpoints you may wonder? They’ll have to make due with a static description. But in our case all externally available API’s are GET/HEAD/OPTIONS only.
Still to figure out
- Having the service invocation macro display the full HTTP response with headers and all.
- Allowing API consumers into the wiki and only display docs for the services to which they have access.
- We also need to figure out a good way of generating a reasonable level of WADL documentation (without being suffocated by Maven et al) and link that from the wiki.
- Then I’m considering providing Schematron documents as contract specs. Those Schematron asserts would of course originate from the API spec compliance tests used in the CI environment.
