Markdoc for API documentation

[PrabhavSF]

Can we use Markdoc for docs generated straight from OAS specs? Are the Stripe API docs generated using Markdoc?

[mfix-stripe]

@PrabhavSF yes! Markdoc is a low enough level toolchain that you can create or generate documents from any source you like, including OpenAPI specs. We are currently exploring ways to generate the scaffolding of our API docs from our spec.

[Patriksafar]

Hey @mfix-stripe I know there are some tools like swagger which could do that, but I wanted to ask if you plan to support that in near future by default.

EDIT: For now I have came up with custom node script which generates the docs from Open api schema - not the perfect solution but for now it works for us.

[nirgilboa]

hey @mfix-stripe is there anything new with generating docs from OpenAPI specs? 🙏🏻 I'm evaluating Markdoc and wondering whether we could include an endpoint or tag within the spec by pointing to it. Obviously we could develop a custom tag for this purpose, but I wonder if something exists already

[adriangalilea]

@mfix-stripe bump

[mfix-stripe]

@nirgilboa @adriangalilea creating a custom tag for this is the way to go! Our own API docs are generated by taking our OpenAPI spec, doing some customizations, creating a Markdoc AST, and then generating a bunch of Markdoc files from each AST. This solution is entirely custom to our infra though, and there isn't much to pull from.

We don't plan on releasing solutions like this, but rather focus on building out the low-level toolchain that is Markdoc, and letting the ecosystem build business-level solutions on top of it.