[RFC] API Software Catalog: Upgrade Catalog Processors to handle API Specs referenced in multiple files with $ref

Status: Open for comments

Need

Current support for Kind: API in Software Catalog is limited to a standalone API Specification file either mentioned completely inline the Catalog definition or referenced in URL with $yaml / $json / $text

It’s a standard practice to write API specifications in multiple files and references them with $ref in the spec files.

While doing a Proof of Concept with three use-cases which are discussed within the Backstage Discord server, it is concluded that the best solution would be to upgrade the Catalog processors to handle this problem.

Sample Error Message we got by doing a $ref to a file present on relative path to the registered catalog file is attached below:

Proposal

The catalog processor can be modified to create a standalone specification in the backend by combining all the $ref references (to a file reference with a path on the VCS or a URL from a host which is in the reading list of Backstage applications). This standalone specification within a catalog definition can be then registered on the Backstage UI successfully.

Alternatives

We are adopting Backstage and would love to see all our APIs on the platform.

If we go with the current product, we would have to spend time and change all our API specifications into a standalone file.

Risks

[datagitlies]

My .02 - provide an option to pass configuration (such as “The URL pointing to API definition”) to the embedded swagger-ui and let it do it’s thing (including following any $ref values). I’m not understanding why “copies” of the definition need to be created anywhere for this use-case. swagger-ui is really good at loading remote OAS definitions via a URL. Of course, there are CORS implications to doing this but it’s not too high of a hurdle for most users. This would also open the door to providing the embedded swagger-ui a configUrl - which would also be nice.

[NishkarshRaj]

@satrox28 @dtuite @lorsatti Please re-assign this RFC to someone else. We do require this feature but our team is focusing on other things. I apologize for leaving this hanging.