https://github.com/osquery/osquery logo
#fleet
Title
# fleet
a

Ahmed

12/18/2020, 6:20 PM
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?
n

Noah Talerman

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.
👍 1
a

Ahmed

12/19/2020, 12:17 AM
Fair enough 👍 I will use that format then for the rest of my documentation contributions.
n

Noah Talerman

12/19/2020, 1:30 AM
Great. The documentation contributions are very appreciated. Thank you!
👍 1
a

Ahmed

12/20/2020, 9:32 PM
It’s my pleasure, I like the project, so contributing to it is the least I can do.
🍻 2
2 Views