Open D063520 opened 2 years ago
:tada: Thanks for opening your first issue here! Welcome to the community!
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
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
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.
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:
It must already be somehoew like this no?
Salut D063520
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.
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!
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.
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?
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.
@sserrata hi! we still would be very interested in this use case! do you think it will be possible at some point?
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