Open API with code snippets

[D063520]

Hi,

Documentation link

https://github.com/PaloAltoNetworks/docusaurus-openapi-docs

Describe the problem

we would like to achieve a functionality that is similar to the one that you present here:

https://docusaurus-openapi.tryingpan.dev/petstore/add-pet

We are starting by the following Open API documentation:

https://qanswer-core1.univ-st-etienne.fr/v2/api-docs

The problem is that we do not get the whole right part, send API request + code snippets.

At the beginning we thought they would be generated from the swagger documentation, but you start from

https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/blob/main/demo/examples/petstore.yaml

which already contains the code snippets. Is this right? How can we achieve a similar input file? I would try to imporve the documentation to indicate this to users ....

Suggested fix

[welcome-to-palo-alto-networks]

🎉 Thanks for opening your first issue here! Welcome to the community!

[sserrata]

Hi @D063520, if you're not seeing the "right part" including the Request and code snippets, please make sure you have docItemComponent: "@theme/ApiItem" configured in your preset or plugin-content-docs config.

Also be sure to wrap the theme:

themes: ["docusaurus-theme-openapi-docs"] // exports ApiItem and ApiDemoPanel

[D063520]

Hi,

I I was able to see everything rendered. But when I do:

import PartialExample from '../api/docs/change-password-using-post.api.mdx';

then I do not see the right part.

Can you explain me how this is working?

Thank you
D063520

PS: basically I would like to use some of the UI components when writing my documentation

[sserrata]

Hi @D063520, which standalone UI component(s) are you interested in using? The generated docs currently do/can not export any components but there might be another way to achieve what you're after.

[D063520]

Hi,

I would be most interested in:

and

But in general I think the library becomes more powerful if one can use all Ui component. At the end they are react components. I imagine something like:

• function to parse open api
• get list of APIs as typescript objects
• have all the UI components and pass as props the object above

It must already be somehoew like this no?

Salut
D063520

[sserrata]

Hi @D063520, I think this is something our plugin/theme could support but it requires some refactoring of the theme components. Currently, they are designed for internal usage, meaning their public usage has yet to be fully explored, e.g. importing standalone components, swizzling, etc.

[D063520]

Hi, I think this would be great added value. Basically the library would also be usable outside of docosaurus. By just refactoring the code you can achieve the functionality of rendering react components from open API documentation. We will try to see if we can achieve it by hacking a bit around .... keep me posted on this!

[sserrata]

Hi @D063520, I think making the OpenAPI docs theme components available outside of Docusaurus is beyond the scope of this project at this time.

One of our main goals is to produce a solution that pairs/integrates well with Docusaurus, specifically because we've had difficulties integrating other OpenAPI doc solutions like Swagger UI, RapiDoc, ReDoc, etc.

Another thing to note is that the current plugin only reads the entire OpenAPI spec while generating the API docs. After that, each API doc/MDX references only a snippet of the OpenAPI spec specific to the operation.

[sserrata]

For what it's worth, I was able to import an entire operation as an MDX partial, but it includes both the ApiItem and the ApiDemoPanel sections. To your knowledge, is there a way to select which parts of a partial you want to include or is it all or nothing?

[sserrata]

Disregard, after further testing it also works simply by including the api frontmatter and using ApiItem to render the doc. That said, we'll need to think more about how to support the use case you brought up.

[D063520]

@sserrata hi! we still would be very interested in this use case! do you think it will be possible at some point?