Improve types, doc, allow spec on ApiSchema, fix showExample

[serut]

I wanted to add the ability to pass the spec param to ApiSchema, I end up with so many changes !!

There is still some FIXME on the code, I let you review and tell me what you think about it

[changeset-bot[bot]]

⚠️ No Changeset found

Latest commit: 438de6270cdc918c30d7b198c2c42088acd5ad8d

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[vercel[bot]]

Someone is attempting to deploy a commit to a Personal Account owned by @rohit-gohri on Vercel.

@rohit-gohri first needs to authorize it.

[vercel[bot]]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Comments	Updated (UTC)
redocusaurus	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Mar 17, 2024 8:38pm

[rohit-gohri]

I like the idea, correct me if I'm wrong but you want to avoid having to add the specs into the configuration and instead want to treat the spec as a doc?

[serut]

Yes, I cannot use the global configuration of redocusaurus as my specs are versionned. On every version of our software, we have the previous and the new spec inside the doc

[rohit-gohri]

Makes sense, what do you think about the idea of adding similar version commands as docs plugin and auto loading all yamls from an openapi folder with the name as ids?

There is some amount of preprocessing that needs to be done on the specs, so directly importing might work for you but not others

[serut]

When you speak about preprocessing spec files, you think about several spec files to merge ? I don't know every use case available.

Managing versionned spec files + preprocessing can be quite hard to do, like how do you know which spec file you need to use with the provided ID ? You will have, for one ID, several specs files, one for each version of the website.

In my project, we create some new microservice sometimes, so spec file can be unavailable for older version (or newer version if we remove a microservice)

[rohit-gohri]

like how do you know which spec file you need to use with the provided ID ? You will have, for one ID, several specs files, one for each version of the website.

I was thinking the same way markdown files are versioned, load files and auto generate ids for them based on path. But I think your approach should also be supported, it makes sense since we are exposing components that can be used in Mdx.

I'll create a separate issue for versioning ( EDIT: created - https://github.com/rohit-gohri/redocusaurus/issues/341 ), I have an idea, will tag you when a PR is ready and you can see if it would work for you

[rohit-gohri]

@serut Depending on how much time you have, you can try to make it backward compatible; or can also just let it be, and in that case I'll cherry pick the relevant changes in a separate PR and add you as a co-author.

Thanks for opening the PR, I really like the idea of being able to just import openapi docs in Mdx without any configuration

[serut]

So far so great, everything looks backward compatible, and types are easier to maintain.

I let you review this MR

[serut]

Did you had time to review this merge request @rohit-gohri ?

[serut]

You can merge it on another branch than master to do some work on it easier (if you cannot push commit on my fork).

Or merge it on master, as you want