feat: Add download file option #1699

zachwhaley · 2021-07-20T17:14:44Z

What/Why/How?

Allows the user to set a download file name and format for the API spec.

For example, openapi.yaml

Reference

Fixes #672

Testing

New tests written

Screenshots (optional)

Check yourself

Code is linted
Tested
All new/updated code is covered with tests

Security

Security impact of change has been considered
Code follows company security practices and guidelines

Allows the user to set a download file name and format for the API spec.

RomanHotsiy · 2021-07-30T08:05:50Z

How about just changing the default to openapi.yaml ?

zachwhaley · 2021-07-30T11:15:47Z

@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.

zcz3313 · 2021-09-09T05:50:05Z

@zachwhaley @RomanHotsiy can this PR be merged? our team needs this feature :)

src/services/RedocNormalizedOptions.ts

RomanHotsiy

I would implement downloadUrl instead (see my comments). Let us plz know if you would be open to do it 🙌

RomanHotsiy · 2021-09-09T08:56:39Z

src/services/models/ApiInfo.ts

@@ -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') {


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.

@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.

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 downloadUrl was 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?

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 <[email protected]>

adamdecaf · 2021-11-19T16:33:19Z

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.

README.md

ivana-isadora

@anastasiia-developer Hi Anastasiia, here's my suggestion for the description, please take a look :)

README.md

…redoc into config-download-file

README.md

anastasiia-developer · 2022-04-22T09:49:07Z

@zachwhaley Hi! Sorry for the huge delay. Thank you for your contribution to redoc.

AlexVarchuk

Looks nice. 🎉

zachwhaley · 2022-04-22T11:17:49Z

Thanks! But removing the ability to download as yaml would mean #672 can’t fully be closed.

RomanHotsiy · 2022-04-22T12:14:17Z

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.

zachwhaley added 3 commits July 20, 2021 12:10

feat: Add download file option

196a2a0

Allows the user to set a download file name and format for the API spec.

npm run prettier

58b5497

js-yaml v4 functions are all safe

b0ebdc0

AlexVarchuk requested changes Sep 9, 2021

View reviewed changes

src/services/RedocNormalizedOptions.ts Outdated Show resolved Hide resolved

RomanHotsiy requested changes Sep 9, 2021

View reviewed changes

Use openapi.json as default

4923037

Co-authored-by: Roman Hotsiy <[email protected]>

RomanHotsiy force-pushed the master branch from c621c6e to aeb276a Compare October 11, 2021 15:25

RomanHotsiy added this to the v2.0 milestone Mar 22, 2022

anastasiia-developer self-assigned this Apr 20, 2022

fix: remove the ability to change the file format

16c80fd

ivana-isadora reviewed Apr 22, 2022

View reviewed changes

README.md Outdated Show resolved Hide resolved

ivana-isadora reviewed Apr 22, 2022

View reviewed changes

zachwhaley requested a review from a team as a code owner April 22, 2022 08:45

zachwhaley requested review from zalesky and anastasiia-developer and removed request for a team April 22, 2022 08:45

ivana-isadora reviewed Apr 22, 2022

View reviewed changes

README.md Outdated Show resolved Hide resolved

ivana-isadora and others added 4 commits April 22, 2022 10:54

Update README.md

f36137f

Merge branch 'master' into config-download-file

5f29219

test: updateSnapshot

e6c1c1d

Merge branch 'config-download-file' of https://github.com/zachwhaley/…

f9f7ced

…redoc into config-download-file

anastasiia-developer reviewed Apr 22, 2022

View reviewed changes

README.md Outdated Show resolved Hide resolved

Update README.md

e310f1f

AlexVarchuk approved these changes Apr 22, 2022

View reviewed changes

anastasiia-developer added 4 commits May 10, 2022 11:26

fix: downloadDefinitionUrl instead of downloadFileName

cecb737

fix: add downloadDefinitionUrl in README.md

32eebd0

test: updateSnapshot

6995a8e

feat: downloadFileName

d0b1309

anastasiia-developer requested a review from RomanHotsiy May 10, 2022 13:15

RomanHotsiy approved these changes May 10, 2022

View reviewed changes

anastasiia-developer merged commit b601c9a into Redocly:master May 10, 2022

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: Add download file option #1699

feat: Add download file option #1699

zachwhaley commented Jul 20, 2021

RomanHotsiy commented Jul 30, 2021 •

edited

Loading

zachwhaley commented Jul 30, 2021

zcz3313 commented Sep 9, 2021

RomanHotsiy left a comment

RomanHotsiy Sep 9, 2021

zachwhaley Sep 9, 2021

RomanHotsiy Sep 10, 2021

zachwhaley Sep 10, 2021

adamdecaf commented Nov 19, 2021

ivana-isadora left a comment

anastasiia-developer commented Apr 22, 2022

AlexVarchuk left a comment

zachwhaley commented Apr 22, 2022

RomanHotsiy commented Apr 22, 2022

feat: Add download file option #1699

feat: Add download file option #1699

Conversation

zachwhaley commented Jul 20, 2021

What/Why/How?

Reference

Testing

Screenshots (optional)

Check yourself

Security

RomanHotsiy commented Jul 30, 2021 • edited Loading

zachwhaley commented Jul 30, 2021

zcz3313 commented Sep 9, 2021

RomanHotsiy left a comment

Choose a reason for hiding this comment

RomanHotsiy Sep 9, 2021

Choose a reason for hiding this comment

zachwhaley Sep 9, 2021

Choose a reason for hiding this comment

RomanHotsiy Sep 10, 2021

Choose a reason for hiding this comment

zachwhaley Sep 10, 2021

Choose a reason for hiding this comment

adamdecaf commented Nov 19, 2021

ivana-isadora left a comment

Choose a reason for hiding this comment

anastasiia-developer commented Apr 22, 2022

AlexVarchuk left a comment

Choose a reason for hiding this comment

zachwhaley commented Apr 22, 2022

RomanHotsiy commented Apr 22, 2022

RomanHotsiy commented Jul 30, 2021 •

edited

Loading