-
Notifications
You must be signed in to change notification settings - Fork 115
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Support multi file OpenAPI definitions #23
Comments
I agree that breaking up specs into multiple files makes for a much better workflow. I think this is possible when generating docs with the redoc cli but not with redocusaurus currently. Even I was using https://github.com/Redocly/openapi-cli to bundle my files into a single yaml. I think this is a valid use case and would like to add it to the project, but I can't be certain when I would get time. If you want to give it a try, feel free to do so and open a PR. redocusaurus/packages/docusaurus-plugin-redoc/src/index.ts Lines 35 to 38 in 783d464
|
A good bundler is the npm openapi tool itself Very poorly documented feature, that generator is listed under "documentation generators" 🙄 It cant also output json if you use Still, its a workaround. |
This will be upcoming in the v1 release. It uses the official redoc openapi-cli under the hood, to maximise compatibility. Also, the bundled yaml will automatically be added as a static asset and used as download url 😄 |
Added in the latest beta! It'll be great if you can test it out and give some feedback : #146 Example added here: https://github.com/rohit-gohri/redocusaurus/blob/releases/v1/website/docusaurus.config.js#L19-L24 |
Hey @EdgarRuizUribe! Happy to help, but best to create a new issue or discussion in the future for questions.
module.exports = {
// ...
presets: [
[
'redocusaurus',
{
// Plugin Options for loading OpenAPI files
specs: [
{
spec: 'openapi/openapi.yaml',
route: '/api/',
},
],
// Theme Options for modifying how redoc renders them
theme: {
primaryColor: '#1890ff',
options: {
// this is what needs to be set:
hideDownloadButton: true,
},
},
},
],
],
// ...
};
That is currently not supported, there is some discussion with different approaches in this issue : #108 . One way is to use MDX files to render nested sidebars. Best to use that issue for further discussions related to this. |
This package is wonderful, and I've been having a blast working on prototyping serving some of my org's Swagger definitions with it. One thing I've run into, however, is an inability to use file refs as specified in https://redoc.ly/docs/resources/ref-guide/
This is fairly easily reproduced by opening up the
example
project in this repo, taking one of the schemas in thecomponents
section of theopenapi.yaml
(for example theApiResponse
component), moving it into a new file, and trying to reference it with$ref: './ApiResponse.yaml'
(which is what I'd named the file I copied the component to).I'm currently getting around this by using https://github.com/wework/speccy to merge my JSON Schemas into the same file as my Swagger API spec, however this is reasonably clunky and makes rapid updates locally a pain. I think that adding this functionality would be fantastic, especially for larger APIs, and even the Redocly team encourages breaking specs up into multiple files for readability/composition.
That all being said, I may just be doing something wrong, and this functionality may already exist within redocusaurus! If this is the case, I bet adding an example of this to the
example
project in this repo would help others who come across the same issue.The text was updated successfully, but these errors were encountered: