mirror of
https://github.com/BookStackApp/BookStack.git
synced 2026-02-05 00:29:48 +03:00
Dedicated API Docs Feature #1430
Reference in New Issue
Block a user
Delete Branch "%!s()"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
Originally created by @ByWaleed on GitHub (Oct 31, 2019).
Describe the feature you'd like
A clear description of the feature you'd like implemented in BookStack.
Allow users to create documentation pages or sections for APIs which could include resource description, endpoints and methods, parameters and examples. API docs can currently be written, but the formatting is time-consuming and doesn't look the best, as the structure of an API document is different from regular program docs.
Describe the benefits this feature would bring to BookStack users
Explain the measurable benefits this feature would achieve.
This could be another feature in the list of features that the app offers and would be more attractive as a complete package, as compared to without the API docs.
Additional context
Add any other context or screenshots about the feature request here.
@ssddanbrown commented on GitHub (Nov 15, 2019):
Hi @ByWaleed,
Thank you for the request with the detail and images.
Unfortunately this is not something I'd look to specifically support as part of the core platform. Here's why:
Focus
Having features for specific types of documentation would require implementation, maintenance & support efforts for functionality that, by design, would only be suited for a specific part of the user-base. Additionally, If we supported this particular type of documentation that would open up the doors to other specific types of documentation, which is something the project could not support at this time.
Existing Solutions
There are many existing solutions out there to write or generate API documentation. API documentation is often done by those with technical proficiency which opens up platform/development/application options in itself. I'd prefer to focus BookStack towards the less-technical audience as that's the gap and core use-case its intended for, A specifically technical feature such as this would be meandering away from that.
Defined Benefits
In your request, the defined benefits are as follows:
Essentially this is stating the benefit would be a potentially wider audience, or more popular platform. I try to stay away from making that a goal in itself, since it can steer the project off it's path resulting in a wider more generalised outcome rather than a richer, focused project.
Apologies that this is probably not the outcome you wanted to hear but hopefully the above explains my reasoning with clarity.
@ByWaleed commented on GitHub (Nov 16, 2019):
Hi @ssddanbrown
Thank you for your comprehensive feedback and the clarity on the matter.
@LukasCCB commented on GitHub (Jan 24, 2023):
Did you find something similar? I wanted it.
Thanks in advance.