The ultimate goal is to have beautiful REST API documentation hosted alongside our Javadoc documentation at api.openmrs.org similar to what you see at developer.github.com/v3/. Having interactive examples interspersed within the text that run against the demo server would be even better.
Ideally, documentation would be coupled with code to avoid divergence/inconsistencies and editing it would be easy for developers as well as technical writers. Some thoughts on how this could be done:
- Manually write API documentation (e.g., in Markdown)
- Pros: straightforward for technical writers and could be easy for devs to edit as well
- Cons: lack of any coupling between docs & code increases chances for mismatch
- Introducing Markdown within Javadocs that could be programmatically turned into documentation.
- Pros: tight coupling of documentation with code
- Cons: might be harder for non-devs to contribute to documentation and harder to see the “big picture” to be consistent across the documentation, there would still likely be introductory or non-resource-specific documentation we’d want to include.
- Manually generate interactive examples from the code using Swagger and then intersperse documentation around the interactive examples.
- Pros: likely easier for non-devs to manage documentation
- Cons: looser coupling between code & documentation could reduce contributions from devs and lead to mismatch between docs & code
- Some combination of approaches (e.g., manually create intro & cross-cutting documentation for things like authentication and pull resource-specific documentation from Javadocs)
- Pros: tight coupling of documentation with code where it matters most while allowing for easier organization and handling of non-resource-specific content like intro, auth, etc.
- Cons: more moving pieces, might be harder for non-devs to contribute to resource-specific documentation
Given GSoD is about documentation, I think generating the text is most important – e.g., writing Markdown documentation introducing the API, covering authentication, and then for each resource with some (perhaps hidden) labelling that would make it easier to move the text into source code in the future if we went that direction.
The extent to which we can document using Swagger or a Swagger-friendly approach, the easier it would be to align this effort with exiting API documentation.