Allow swagger URL and not just swagger file

[SkedGoDeploy]

Context

Currently, Apinf only allows API Managers to upload Swagger file to be rendered in the documentation browser.

User story

As an API Manager
I would like for Apinf to render a Swagger file hosted on a third party server
so I can develop and host my swagger file elsewhere and not have to manually upload changes

Feature request

Allow API Managers to specify a URL pointing to a Swagger file somewhere on the Internet. When the URL is provided, the Swagger file should be rendered in the Swagger UI.

Definition of done

• User can choose whether they want to upload a file or add a URL for showing a Swagger document in the Swagger UI
• If the user adds a URL, it needs to be stored for the purpose of showing the file in the Swagger UI
• When the user has made a selection, the other option should be disabled

Note: this solution should not affect the possibility of adding external documentation links

Original request

This is so that when we update our swagger file on our site, we don't have to remember to upload it to apinf.io

Wireframe

On opening the Manage dialog, user will now see Documentation link option and Documentation upload function appearing as radio buttons.
Selecting one option would disable the other option and vice versa. This is mentioned with instruction texts.
A feedback using S-alert can be shown mentioning which option has been enabled and which one disabled.

[bajiat]

Thanks for you interest in Apinf! This is a good idea and we can definitely consider this. I think it would be worthwhile to provide an option to either upload a file or to provide a link. Both of these would render in the Swagger UI. Does this meet your needs?

[bajiat]

Definition of done

• User can choose whether they want to upload a file or add a URL for showing a Swagger document in the Swagger UI
• If the user adds a URL, it needs to be stored for the purpose of showing the file in the Swagger UI
• When the user has made a selection, the other option should be disabled

Note: this solution should not affect the possibility of adding external documentation links

[brylie]

@bajiat and @SkedGoDeploy I updated the task description, moving the Definition of done and adding some more context.

[bajiat]

Comment for the Documentation URL: Note that the URL field could be used both for Swagger link and link to any other external documentation. If the URL points to a Swagger file, it is shown in the Swagger UI. If the URL points to any other resource, it is displayed as a link in the external documentation section.

[brylie]

If the URL points to a Swagger file, it is shown in the Swagger UI. If the URL points to any other resource, it is displayed as a link in the external documentation section.

This would likely require logic to parse the remote content in order to determine whether it is a swagger file. Parsing would probably happen each time the page is rendered, since it is possible for the remote contents to change at any time.

For the above reasons, I recommend we explore alternative designs, so we can weigh complexity/simplicity/usability of multiple designs.

[55]

@Nazarah here is idea we came up with @brylie @bajiat

For now we keep external link to documentation as it is now, and will try to combine it with swagger link as a future enhancement.

For swagger part we can have option to enter URL of documentation file, and render it on Save.
Also we allow user to upload multiple swagger documentation files and choose what to render.

[Nazarah]

hi @NNN , I came up with these designs from your feedback.

1. When there is no documentation available, on clicking the manage button, the dialog shows three fields to upload swagger file, to add a link for swagger file and a field for external documentation. As long as no file uploaded, the method pane is inactive.
   

2. On uploading a file, the try-methods become activated. Also user can delete the file if s/he wants to.
   The URL of the swagger file also gets populated in the related field.
   

3. Without uploading any swagger file from APINF, user can also give link to a swagger file. In such case the try-out methods remain inactive.

4. User can also provide external documentation URL here

I am really not in favor of displaying older versions files in the manage dialog.
We can always create a separate pane in the Documentation tab and show the older version swagger files with pagination facilities.

@bajiat @brylie what do you think about it?

[bajiat]

@Nazarah Good work! There may be some room for improvement for the instruction text and the field labels, but other than that I would say this is now ok.

Instruction text

You can upload and API documentation file (Swagger) or provide a link to your API documentation file. The API documentation file is rendered in the Documentation viewer. You can also provide a link to other external documentation related to your API, for example HTML documentation.

Field labels

"Link to API Documentation" > "Link to API Documentation File"
"Link to other API Documentation" > Link to Other Documentation