Openapi support in markdown #2755

New Issue

OVERLORD · 2026-02-05T05:02:52+03:00

OVERLORD commented

2026-02-05 05:02:52 +03:00

Originally created by @codeasashu on GitHub (Apr 18, 2022).

Describe the feature you'd like

I have a lot of technical docs and most of them are apis. So, its natural to assume that they have openapi compatible documentations (yaml format).

I have to host another instance of redoc just to be able to read them. It will be cool if bookstack can provide the ability to render the api documentations too. A single column swagger doc would be nice.

Describe the benefits this would bring to existing BookStack users

Users won't have to leave bookstack to view api documentations
Documentations can be changed inside markdown, just like other technical docs
consistancy

Can the goal of this request already be achieved via other means?

Iframes can be one way but then the core api doc still has to be hosted somewhere.

Have you searched for an existing open/closed issue?

I have searched for existing issues and none cover my fundemental request

How long have you been using BookStack?

6 months to 1 year

Additional context

No response

Originally created by @codeasashu on GitHub (Apr 18, 2022). ### Describe the feature you'd like I have a lot of technical docs and most of them are apis. So, its natural to assume that they have openapi compatible documentations (yaml format). I have to host another instance of redoc just to be able to read them. It will be cool if bookstack can provide the ability to render the api documentations too. A single column swagger doc would be nice. ### Describe the benefits this would bring to existing BookStack users - Users won't have to leave bookstack to view api documentations - Documentations can be changed inside markdown, just like other technical docs - consistancy ### Can the goal of this request already be achieved via other means? Iframes can be one way but then the core api doc still has to be hosted somewhere. ### Have you searched for an existing open/closed issue? - [X] I have searched for existing issues and none cover my fundemental request ### How long have you been using BookStack? 6 months to 1 year ### Additional context _No response_

OVERLORD added the 🔨 Feature Request label 2026-02-05 05:02:52 +03:00

OVERLORD closed this issue

2026-02-05 05:02:54 +03:00

OVERLORD commented

2026-02-05 05:02:57 +03:00

@ssddanbrown commented on GitHub (Apr 18, 2022):

Thanks for the request @codeasashu,

What exactly do you mean when saying "in markdown"? You can already embed yaml code blocks within a markdown document, is the expectation that these specific sections would show as an interactive list of endpoint details within the displayed page?

My issue with this is that it would likely be a significant feature to support that only serves a very specific BookStack audience segment. I'm not sure it'd be worthwhile for us to add to the core project.

@ssddanbrown commented on GitHub (Apr 18, 2022): Thanks for the request @codeasashu, What exactly do you mean when saying "in markdown"? You can already embed yaml code blocks within a markdown document, is the expectation that these specific sections would show as an interactive list of endpoint details within the displayed page? My issue with this is that it would likely be a significant feature to support that only serves a very specific BookStack audience segment. I'm not sure it'd be worthwhile for us to add to the core project.

OVERLORD commented

2026-02-05 05:03:07 +03:00

@codeasashu commented on GitHub (Apr 18, 2022):

@ssddanbrown adding a yaml in markdown is possible. However, if we can wrap the yaml with a specific tag (eg. openapi), then maybe we will be able to render the api documentation.

I know this only serves particular user segment, but if I am to add a PR, would it be accepted?

@codeasashu commented on GitHub (Apr 18, 2022): @ssddanbrown adding a yaml in markdown is possible. However, if we can wrap the yaml with a specific tag (eg. openapi), then maybe we will be able to render the api documentation. I know this only serves particular user segment, but if I am to add a PR, would it be accepted?

OVERLORD commented

2026-02-05 05:03:15 +03:00

@ssddanbrown commented on GitHub (Apr 19, 2022):

I know this only serves particular user segment, but if I am to add a PR, would it be accepted?

Probably not. It's unclear what the implications would be and I think it would likely not be worthwhile for adding to core. It's not something that fits with the rest of the content types (Due to its non-aligned view/edit states) and I'd imagine the output format would be quite subjective and open to opinion while opening us up to needing to know and support the OpenAPI spec feature-set. Then there's questions in how this works/displays with the WYSIWYG editor, How this functions for exports/print.

@ssddanbrown commented on GitHub (Apr 19, 2022): > I know this only serves particular user segment, but if I am to add a PR, would it be accepted? Probably not. It's unclear what the implications would be and I think it would likely not be worthwhile for adding to core. It's not something that fits with the rest of the content types (Due to its non-aligned view/edit states) and I'd imagine the output format would be quite subjective and open to opinion while opening us up to needing to know and support the OpenAPI spec feature-set. Then there's questions in how this works/displays with the WYSIWYG editor, How this functions for exports/print.

OVERLORD commented

2026-02-05 05:03:19 +03:00

@ssddanbrown commented on GitHub (May 9, 2022):

As per my above reasoning, I'm going to close this off as out-of-scope for being adding to the core.

@ssddanbrown commented on GitHub (May 9, 2022): As per my above reasoning, I'm going to close this off as out-of-scope for being adding to the core.

OVERLORD commented

2026-02-05 05:03:23 +03:00

@Jonn3y commented on GitHub (Jul 18, 2022):

I would also be interested in this feature. Even so the issue is closed

@Jonn3y commented on GitHub (Jul 18, 2022): I would also be interested in this feature. Even so the issue is closed

OVERLORD commented

2026-02-05 05:03:27 +03:00