@ayesh & @batbrain7, please take a look at 5 Examples of Excellent API Documentation (and Why We Think So) and 7 Items No API Documentation Can Live Without.
I’m far less interested in another round of Swagger documentation tweaks producing variations on this, where pretty colors, rounded boxes, and interactive “documentation” get prioritized over descriptive content. What the OpenMRS community really needs is clean & concise, well-written documentation of our REST API that targets both introduction (for those new to the API) and reference (for those looking for details on a part of the API they haven’t used lately). We also need to keep things simple, since it’s important to produce something that can be maintained. There are several documentation generators around we could consider; just ask google or find lists like this… but I’d be fine to start with simple Markdown.
These are the types of things that I’m thinking about regarding REST API documentation:
- Use Markdown
- Prioritize concise, pragmatic, descriptive content (e.g., teach someone how to authenticate to the REST API in a few minutes, explain what’s working for orders and what isn’t).
- Support syntax highlighting, since good examples are priceless
- Avoid the shiny/attractive niche tool that might be abandoned in 1-2 years
- Search, table of contents, support for translations of the API are nice-to-haves, but lower priority than having quality content.
- We’ll want to create a backlog (prioritized list of things to document) and then divide & conquer.