Skip to content
GitLab
Open
Issue created by Administrator@rootContributor

[Discussion] Generator Compatibility Check and Table

Created by: grokify

Overview

This is a discussion of some items that I think could increase adoption of OpenAPI Generator for discussion. Two goals include:

  1. Provide API publishers and users a high degree of confidence that an API of interest with a spec is supported by generators of interest. The idea is similar to Browser Compatibility Tables but with a report specifically for a given API. This should include OAuth, requests, responses.
  2. Provide the OpenAPI Generator community with information on gaps of popular features or specific features in popular APIs, which if supported, could increase adoption of OpenAPI Generator for those developer communities.

These can lead to:

  • more API publishers using OpenAPI Generator client SDKs as their official SDKs
  • more API users using OpenAPI Generator client SDKs, vs. creating their own manually

I'm interested in contributing to this given I'm both API publisher and user. As a publisher, I want to support multiple languages with official and community SDKs and it would be nice to easily see how much support there is for my APIs across a set of languages. As a consumer, I work with many different APIs and it would be useful to see each of those for my languages of choice.

What to Build

The following are some items that may be useful to make this happen, going from the end product backwards.

  1. Online Readiness Reporter: this would allow the input of a spec via URL or copy/and paste. In addition to validating the spec, this readiness reporter will present a table of what is supported vs. not supported by selected generators. If everything is supported, then the user is good to go. If not everything is supported, they know the delta and can move ahead with the client with that information.
  2. Generator Compatibility Tables: Build a general OpenAPI Generator version/language support table. This is similar to Browser Compatibility Tables. (e.g. https://caniuse.com/, https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage#Browser_compatibility). Ideally this would be auto-generated from reviewing CI test logs. This would be useful for checking for a specific feature but many API sets are large so the spec-to-compatibility-table report is important.
  3. Test API Spec Enhancements: the compatibility tables could be auto-generated if we had more tests that all generators can use. We would need to match specific tests to features in the compatibility table. One option in this particular test spec is to have the operationId or an x-property indicate which tests are supported. An x-property could support multiple capabilities per endpoint.

Additional Items

  1. End Test Cases / Generator for OpenAPI Non-Supported Features: Some APIs have features that are not well supported in OpenAPI spec. We could come up with alternatives to implementation using x-properties and implement them in clients to increase adoption. At the same time, we could make a case to the OpenAPI Initiative for the importance of certain capabilities given increasing adoption.

Considerations

  1. Lengthening Test Times: This approach would have many more test cases and could lengthen integration test times.

Existing Work

  1. We already have a number of tests that we could organize into a compatibility table and report to see functionality across generators. We would need a set of spec endpoints that could feed a compatibility report, tests against those endpoints, and a report system to consolidate the results.