search

aep-dev / aeps

AEPs help developers and organizations build clear, consistent network APIs and clients by providing an extensible set of design guidelines.
http://aep.dev/
Other
21 stars 15 forks source link

proposal: upgrade openapi definitions to 3.1 #213

Open toumorokoshi opened 2 months ago

toumorokoshi commented 2 months ago

Today, all of aep.dev uses openapi 3.0 definitions.

Given the nascence of the project and our decision to control our own toolchains, we have some freedom to update the OAS version and not pay a painful migration in the future.

OpenAPI 3.1 has advantages, like allowing the usage of JsonSchema as a standard for resource descriptions. If we can upgrade to OAS 3.1 - we should.

The OpenAPI generator is also adding support for 3.1 as well: https://github.com/OpenAPITools/openapi-generator

earth2marsh commented 1 month ago

Even though 3.1 does not have strong uptake yet, I think there is a case to be made for picking 3.1, especially because it seems to me that AEPs are more about building new services in an API design-first approach (rather than upgrading legacy services).