How to generate API Docs in Markdown Format (.md)?

[silverbucket]

I can't find any documentation on outputting markdown, rather than html, when generating the API docs. Is there any clear and direct documentation on how to generate Markdown API docs (or what outputs are supported)?

[tatomyr]

Hi @silverbucket, what do you mean by generating Markdown API docs? Do you mean you want docs to be produced in Markdown when using build-docs command?

[silverbucket]

@tatomyr Correct, instead of HTML API Docs I'd like Markdown (to keep the files readable in git).

[tatomyr]

Unfortunately, it's not possible. Redocly CLI uses Redoc to generate the output file, and the only format is Html. Here are the corresponding docs for Redoc and for the build-docs command.

I'm closing the issue. If you think Redoc should support the Markdown format, please open an issue in its repository.

cc @AlexVarchuk

[AlexVarchuk]

OSS Redoc support markdown. You can check it on the playground page.
For example, that page includes a markdown in info->description:

...
description: |
    This is a sample server Petstore server.
    You can find out more about Swagger at
    [http://swagger.io](http://swagger.io) or on [irc.freenode.net, #swagger](http://swagger.io/irc/).
    For this sample, you can use the api key `special-key` to test the authorization filters.

    # Introduction
    This API is documented in **OpenAPI format** and is based on...
....

@silverbucket Could you clarify your problem and we'll try to help you?

[silverbucket]

@AlexVarchuk I think this is the confusion, I see markdown support mentioned a lot in the docs, yet it's unclear and not really spelled out anywhere that the output is only HTML, and the markdown support is for input data.

What I was looking for is to output markdown using my openapi_spec.json file as the source.