Manage API Documentation modal somewhat confusing

[brylie]

Context

The ManageAPI Documentation modal has two fields for linking remote API documentation. One field expects an OpenAPI Specification file, while the other field is used for any other type of link (e.g. a rendered API documentation portal).

Problem

Having two fields with similar names is somewhat unclear:

• Link to API Documentation
• Link to other API Documentation

Goal

Clearly differentiate the API Documentation fields. Help users understand how the fields work, and what type of link to provide (e.g. an OpenAPI Specification or plain HTML).

Bonus: unify the fields, so the user does not have to differentiate the field types.

Example

In the APInf.io API Catalog, the Apifonica - calls & SMS was configured with API Documentation. However, the configuration was incorrect, as a regular web page was provided in the field that expected an OpenAPI Specification file.

[Nazarah]

@brylie do you have any solution in your mind on how to address this? Perhaps renaming the label so that it specifies that the file has to be OpenAPI specification or json/yaml file?

[brylie]

The solution could be as simple as changing the UI text, such as the form labels.

[Nazarah]

@brylie the info tool beside Add Documentation label already gives information about the file to be swagger json or yaml. Also the label can be changed as: "Provide Swagger or OpenAPI Documentation via"