Allow users to download swagger file

idea

(Arie Gofer) #1

Is there a simple way to include “download swagger file” link on my OpenAPI documentation pages, to download the .oas2 file of this page?
thanks !


Using links in documentation - problem with ampersand sign
(Vincenzo Chianese) #2

Hey,

in case your API is public, Stoplight provides a way to get a direct link to your file and make it available for your users to download.

All you need to do is go in your project, figure out its ID, the branch you want to expose and then construct an URL based on these informations. For instance:

https://next-api.stoplight.io/files.export?projectId=13625&branch=version%2F1.1&path=petStore.oas2.yml

I hope that helps/clarify. To get more info, you can visit our documentation section on the topic


(Arie Gofer) #3

Thanks @vncz. I was aware of this option, but it is not good enough.
My project is private, and I share the hub with the developers. I need a way for them to be able to download the swagger files. (preferably as a link from the hub).
I was actually under the impression that once I protect the hub using username/password they will have access to the files once they log in, but I was wrong.
So I am back to square one - I can share the documentation with them, but no way to share the files.
Any suggestion?
Thanks!


(Vincenzo Chianese) #4

Ah ok, I see what you mean.

This feature is currently on our backlog and hopefully it’s not a big change.

We hope to work on it soon™. I’m going to ask for a status update and see if I can give you an ETA or at least an update.


(Arie Gofer) #5

perfect @vncz. looking forward hearing about the plans.
thanks !


(Arie Gofer) #6

@vncz,
Sorry to nudge :). This becomes a real issue as I need to provide access to the swagger files to our developers.
Is there any forecast?
Thanks !
Arie


(Vincenzo Chianese) #7

Hey @agofer,

We’re looking into the alternatives to make it happen. As soon I have news on this regards, I’ll make sure to post it here.


(Taylor Barnett) #8

Hey @agofer, have you checked out exporting it with a token? I talk more about it here:


(Arie Gofer) #9

@taylor,
Yes, I saw it before posting my question. it is a little cumbersome IMHO.
That said, if the authentication token can be sent as a querystring parameter, then it can be a great workaround for my needs.
thanks !


(Taylor Barnett) #10

We’re working on adding this in the next sprint. So hopefully it will be a nicer experience soon.


(Arie Gofer) #11

@taylor this is great. Thanks !


(Taylor Barnett) #12

Just checked internally, and this is still in progress for the next release. I’m checking in to see how close it is to be done and will share updates here as I know more info.


(Taylor Barnett) #13

This is in code review right now.


(Arie Gofer) #14

Any news on this one? Thanks !


(Taylor Barnett) #15

This is live on the web app right now! We haven’t posted the changelog for v4.8.0 in the forum just yet because the last steps for the desktop release are being done now.

But you can catch a sneak peak of it here: https://stoplight.io/blog/stoplight-v4-8-0


(Taylor Barnett) #16

@agofer let us know what you think after you get a chance to check it out now that it is live both in the web and desktop apps.


(Arie Gofer) #17

Yep. This is working great. Many Thanks !
The only issue I can see with this approach is with referenced entities. I have entities defined in other files with REF. When someone downloads the file - he does not have the referenced entities. I am not sure I have a good idea as for how to solve it.


(Arie Gofer) #18

@taylor Quoting one of our developers : “COOL!”


(Taylor Barnett) #19

Is this happening in one of your published Hubs? The reason I ask is because it should be resolving remote $refs. But you might not see this if it isn’t published yet.


(Arie Gofer) #20

@taylor
I stand corrected ! Sorry
I tried it from the “read” and not through a published hub. Now I tried it from the hub and this is PERFECT!!!
Thanks !