Adopting the OpenAPI schema to generate Plaid’s SDKs

Ideally, we wanted one source of truth for our API in order to enforce a consistent experience for external developers, which is why we decided to use an OpenAPI schema as a point of reference to generate the docs, the client libraries, and part of our API.We learned some valuable lessons along the way that we wanted to document and share so that other teams taking on similar projects could benefit. PhilosophyWhen we first started generating our SDKs, the bulk of the issues we ran into initially were around making sure our OpenAPI schema was an accurate representation of our API. However, after we resolved most of these issues, we started running into another class of problems - issues with the generated output of the libraries. OpenAPI schema: sometimes we could use different methods of representing the API within OpenAPI. Also, some features of the OpenAPI version we used weren't fully implemented by all the code generators - we would abstain from using these features. The actual generator implementation: The project that we ended up using for code generation is OpenAPI Tool's generator. Another added bonus of not modifying the generator is that other developers outside of Plaid can generate a working library without using our forked generator! Modify our API and OAS to match an OpenAPI authentication schema. Since we were opposed to modifying the generator, we decided to adopt an OpenAPI authentication schema.