API Documentation Format
I noticed you currently use pure Markdown file for the API documentation, would it be okay to switch to OpenAPI format? There are a couple of reasons I think this would be a good move:
• The format is almost a standard and can be parsed by a lot of tools which makes testing, and spinning mock servers much easier.
• In case the API documentation will be added to the website or published a more structured format, doing that will be a simpler conversion or running it through a tool.
• Easier to contribute to since there are many editors that simplify the process of adding new endpoints and request/response details.
Do you think it will be okay if I switched to this format and sent my PR for the rest of the documentation in OpenAPI format?
12/18/2020, 9:46 PM
Hi Ahmed. Thanks for the suggestion as well as the list of benefits in using the OpenAPI format. The format/tool looks powerful.
Given that we’re just beginning to expand the API documentation, we’re going to continue using the pure markdown file/formatting.
12/19/2020, 12:17 AM
Fair enough 👍 I will use that format then for the rest of my documentation contributions.
12/19/2020, 1:30 AM
Great. The documentation contributions are very appreciated. Thank you!
12/20/2020, 9:32 PM
It’s my pleasure, I like the project, so contributing to it is the least I can do.