Skip to content
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

Export dereferenced files from Studio #126

Closed
rossmcdonald opened this issue Sep 20, 2019 · 12 comments
Closed

Export dereferenced files from Studio #126

rossmcdonald opened this issue Sep 20, 2019 · 12 comments

Comments

@rossmcdonald
Copy link
Collaborator

@rossmcdonald rossmcdonald commented Sep 20, 2019

Currently there is no way to retrieve a fully dereferenced API description from Studio directly (you have to publish and then retrieve it from the docs/explorer).

@marbemac marbemac added the p:medium label Oct 2, 2019
@philsturgeon philsturgeon changed the title Provide a way to retrieve dereferenced files from within Studio Provide a way to retrieve bundled files from within Studio Oct 2, 2019
@philsturgeon

This comment has been minimized.

Copy link
Contributor

@philsturgeon philsturgeon commented Oct 2, 2019

Can we have an "Export" right click on the API?

Screen Shot 2019-10-02 at 19 53 56

Could also be a floaty icon next to the API, maybe some triple dots or something.

For now just do it in the appropriate format, we can do Export (in other formats) later.

@philsturgeon

This comment has been minimized.

Copy link
Contributor

@philsturgeon philsturgeon commented Oct 4, 2019

@benjdl @miguelgf giving you both a quick mention so you get notifications, as you both wanted this functionality.

@benjdl you mentioned YAML/JSON, that's a good point, my screenshot would not cover giving users the choice.

If the context menu (and ... for those who don't think to / cant right click) is just "Export" then we can have a little modal asking for which data format:

  • OpenAPI v3.0 JSON
  • OpenAPI v3.0 YAML

In the future this could offer OpenAPI v3.1 and RAML and whatever else but we dont have to deal with that now.

@philsturgeon philsturgeon changed the title Provide a way to retrieve bundled files from within Studio Export bundled files from Studio Oct 4, 2019
@rossmcdonald rossmcdonald added p:high and removed p:medium labels Oct 24, 2019
@benjdl

This comment has been minimized.

Copy link

@benjdl benjdl commented Oct 25, 2019

I'm currently using the package https://github.com/WindomZ/swagger-merger to do this "export":

./node_modules/swagger-merger/bin/swagger-merger.js -i ./documentation/reference/*my-api*/openapi.yaml -o full-documentation.yaml

Maybe it could help you, anyway if someone needs a temporary solution here it is.

@marbemac

This comment has been minimized.

Copy link
Member

@marbemac marbemac commented Oct 28, 2019

How about as a first step, an "Export Dereferenced" context menu item on api and model files (similar to what Phil described), that copies to clipboard + displays a success notification to let the user know it's in their clipboard? Nice and simple to start - thoughts @P0lip @philsturgeon @benjdl @rossmcdonald @mallachari?

@P0lip

This comment has been minimized.

Copy link
Member

@P0lip P0lip commented Oct 28, 2019

@marbemac
Sounds good. I believe we might need some progress bar or something similar, as JSON Schema models are not dereferenced by default until activated, meaning it might take a bit of time in certain circumstances for dereference to take place.

@mallachari

This comment has been minimized.

Copy link

@mallachari mallachari commented Oct 28, 2019

Sounds good. I believe we might need some progress bar or something similar

Maybe just two notifications and disabling export during dereferencing?

@philsturgeon

This comment has been minimized.

Copy link
Contributor

@philsturgeon philsturgeon commented Oct 28, 2019

Are we aiming for a bundled file (all external $refs changed to internal $refs) or dereferenced (literally no $ref's left in the file at all because all contents of the $ref target were copied and pasted into the one megafile)?

I think we should be aiming for bundling, and if people demand the much bigger slower bulkier option of dereferenced files then we can add that as an option?

Does it have to copy to keyboard or can we offer a "Save File" view? I can put myself in a users shoes and imagine some confusion there.

@benjdl

This comment has been minimized.

Copy link

@benjdl benjdl commented Oct 30, 2019

@philsturgeon I think we should have these two options:

  • "Export bundled files
    -> Save to JSON
    -> Save to Yaml"
  • "Export dereferenced file
    -> Save to JSON
    -> Save to Yaml
    -> Copy to Clipboard"

The package I've shared use the dereferenced method and it does it really quick, although I've not used it intensively or with a very large documentation.

@philsturgeon

This comment has been minimized.

Copy link
Contributor

@philsturgeon philsturgeon commented Nov 1, 2019

This is happening in a very simple form with just copy to clipboard, but will return in the future with a fancy options modal. We're not going to be able to avoid offering various options for Export.

@marbemac marbemac changed the title Export bundled files from Studio Export dereferenced files from Studio Nov 13, 2019
@marbemac

This comment has been minimized.

Copy link
Member

@marbemac marbemac commented Nov 13, 2019

Initial delivery in Studio v1.5 (right click on model or openapi file, see export option) - closing this one. Can open separate issue later for bundled export, which is more involved.

@marbemac marbemac closed this Nov 13, 2019
@philsturgeon

This comment has been minimized.

Copy link
Contributor

@philsturgeon philsturgeon commented Nov 25, 2019

Exporting as a file got done too! Look out for it in an upcoming version. Thanks everyone, especially @mallachari!

69497311-77184d80-0f16-11ea-972b-8d478ce2cb81

@benjdl

This comment has been minimized.

Copy link

@benjdl benjdl commented Nov 26, 2019

Great Job, thank you very much ! ;)

@StoplightDeb StoplightDeb added qa approved and removed qa-approved labels Dec 2, 2019
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
7 participants
You can’t perform that action at this time.