feat: Add download file option #1699
Conversation
Allows the user to set a download file name and format for the API spec.
|
How about just changing the default to |
|
@RomanHotsiy I believe there are still folks that would like the option to provide a JSON file as that is a valid format. I did not change the default just to keep backwards compatibility. |
|
@zachwhaley @RomanHotsiy can this PR be merged? our team needs this feature :) |
src/services/models/ApiInfo.ts
Outdated
| @@ -35,7 +41,13 @@ export class ApiInfoModel implements OpenAPIInfo { | |||
| } | |||
|
|
|||
| if (IS_BROWSER && window.Blob && window.URL && window.URL.createObjectURL) { | |||
| const blob = new Blob([JSON.stringify(this.parser.spec, null, 2)], { | |||
| let specString: string; | |||
| if (path.extname(this.options.downloadFileName) === '.yaml') { | |||
There was a problem hiding this comment.
we ignore the yaml dumper as it adds a lot of code to the bundle: https://github.com/Redocly/redoc/blob/master/webpack.config.ts#L116
Can we instead implement a downloadUrl option so you can provide any URL and don't have Redoc to serialise the definition.
There was a problem hiding this comment.
@RomanHotsiy I'm not sure I understand what a downloadUrl option would entail. Are you suggesting users would provide their own URL for downloading a YAML API spec? If so, what if the URL they provide does not contain the API spec or is inaccessible?
I had originally hoped that the original API spec file used to create the webpage would be available to use for download, but that did not seem to be the case or I did not know where to look for it.
There was a problem hiding this comment.
The original URL should work fine as long as you use URL and not use redoc-cli from a file on the filesystem (it should actually work like that but there may be a bug or something).
So I think it should work as below:
- if URL was used in Redoc settings - the download button should just point to this URL
- if a local file was used (e.g. redoc-cli) - it should use user-provided
downloadUrl. - if a local file was used and no
downloadUrlwas provided, then we just serialize it to json and use openapi.json as filename (JSON is free in terms of bundle size vs yaml).
What do you think?
If so, what if the URL they provide does not contain the API spec or is inaccessible?
The purpose of this option is to provide the URL for download button. Why should anybody provide a bad URL there?
There was a problem hiding this comment.
Sorry, I wasn't familiar with the multiple options for providing an API spec file; I believe our use case uses the redoc-cli.
So is there already an API spec URL that can be referenced in the code? Or are you suggesting this be added; if so, would this URL be used to generate the HTML or would it just be for downloading an API spec file?
Why should anybody provide a bad URL there?
I don't think it would be intentional, e.g. is it possible to use an internal or local company URL to generate the HTML pages? If so, that URL might not be accessible to the wider internet.
Co-authored-by: Roman Hotsiy <gotsijroman@gmail.com>
|
Is there anything I can help with this to get it merged? Having a stable download URL would really help us auto-generate client code for multiple languages. |
There was a problem hiding this comment.
@anastasiia-developer Hi Anastasiia, here's my suggestion for the description, please take a look :)
zachwhaley
requested review from
zalesky and
anastasiia-developer
and removed request for
a team
|
@zachwhaley Hi! Sorry for the huge delay. Thank you for your contribution to redoc. |
|
Thanks! But removing the ability to download as yaml would mean #672 can’t fully be closed. |
We will have to close it as WON'T FIX. We don't want to add a heavy yaml dump dependency which will increase a bundle size for this use-case. Maybe, we will consider something comparable: if the source was yaml we can save yaml too. |
What/Why/How?
Allows the user to set a download file name and format for the API spec.
For example,
openapi.yamlReference
Fixes #672
Testing
New tests written
Screenshots (optional)
Check yourself
Security