feat(openapi): Update oas file based on title

[garrett-wade]

🚥 Fix RM-XXX

🧰 Changes

Added the --matchOnTitleAndVersion parameter to the openapi command. This allows for an API Specification to be updated based on its title and version rather than a specific id in the readme database. This prevents a developer from having to know the id of the api spec they are updating improving the developer experience. Additional update include:

1. Updated the prepareOas.ts file to return a the API Specification title
2. Added the getSpecifications.ts file in the lib to get all API specifications for a given project and paginate through the results.
3. Add test coverage for all changes

🧬 QA & Testing

1. Create a valid api spec locally
2. Upload the api spec using rdme openapi
3. Make a change to the api spec but ensure it has the same title
4. Update the api spec using rdme openapi --matchOnTitleAndVersion without using the --id parameter.

[erunion]

I don't want to speak for @kanadgupta here but I'm leaning towards not pulling this in. This kind of upload flow is something we've been tossing around over the past month or two and I'd rather we do that ¹, and make that the default experience than adding another new flag we need to maintain within the ever growing complexity of the openapi command.

Footnotes

1. Doing this is going to require a complete overhaul to how we sync specs and we haven't quite cracked the nut of how to accomplish it. It's something we're actively thinking about though because giving users a spec ID they need to capture and maintain is a bad experience. ↩

[garrett-wade]

@erunion @kanadgupta up to you both, do you have any sort of timeline for the enhancements to be delivered? We are encountering friction with developers as well as setting up our CI/CD, process for publishing.

[erunion]

@garrett-wade No timelines as we're still formulating a plan for how it'll work, but we'd love to do it this year.

[kanadgupta]

Unfortunately I agree with @erunion—the complexity of the openapi command and the number of edge cases is becoming pretty unwieldy as is, and this feels like a bandaid for a broader underlying DX issue.

@garrett-wade could you elaborate on what your CI/CD use case is? As a short term solution, perhaps the changes in #577 could help with this?

[garrett-wade]

@kanadgupta Understood, the main issue is that there is nothing in the OAS file that can be specified to denote where it should go in Readme when uploaded. Rather the CI/CD job has to be configured to do so. This works nicely with docs because the user can specify a category id and slug in the grey matter, but there is no way do do this for an api spec rather than tracking the id of the doc after uploading and ensuring you save that for future use.

[kanadgupta]

Gonna close this out — we have some API changes in the works that should address this issue and will also benefit our non-rdme users of the ReadMe API. Stay tuned!