In this talk, I'll introduce the audience to the potential of OpenAPI in simplifying and enhancing the development process for React applications. I will demonstrate how OpenAPI can be harnessed to seamlessly autogenerate REST APIs, streamlining the consumption of data within React projects. With a keen focus on efficiency and reliability, attendees will gain valuable insights into implementing automated tests to ensure robustness and quality in their applications.
Video Summary and Transcription
Today's Talk covers the challenges of developing APIs and the available tools to simplify the process. It also demonstrates building a pizza menu application using React and Fastify, with documentation and SDK generation using Swagger and OpenAPI. Orval is introduced as a tool for generating mutations, testing with mock service worker-generated mocks, and using Zod for validation. It supports multiple languages and frameworks, and allows consuming APIs from various resources. The SDK can be tracked using version control, and Open API specifications can generate Swagger UI and Redux doc asserts.
Available in Español
1. Introduction to APIs and their Challenges
Short description:
Today, I'm going to talk about the challenges of developing APIs and the tools available to make it easier.
OK, so we just have five minutes, so I'm going to drive it like I stole it. My name is Teodor, I'm a software engineer based in Athens, Greece, I'm working for Proxima Analytics, which is an ethical open source analytics platform. And today I'm going to make just another talk about APIs. And I can tell you that during my career I have developed so many APIs. And I can really tell you that developing APIs is pretty damn hard. You have to think about code changes, documentation, breaking stuff, type safety, like consuming them from different clients or different applications and so on. And there are tools out there, like GraphQL Cogent, ERPC, you name it, that they can kind of semi-automatically generate SDKs in order to consume them into your applications. But that can be a bit tricky and it can be really coupled with the framework we are actually using.
2. Building a Simple Pizza Menu Application
Short description:
Today, we're going to build a simple pizza menu application using React and Fastify. We'll use Swagger and OpenAPI to document our APIs and generate SDKs. The Fastify React UI provides full documentation and testing capabilities. To generate our SDK, we'll use Orval, which supports different frameworks and fetching libraries. We can list and create pizza menu items easily.
So today we're going to try something simple, just under five minutes, we're going to try and build a simple pizza menu application. We're going to use React and Fastify, React obviously, and Fastify as a server. And as always, type safety is a must. So let's get this one started quickly.
We have a really basic setup about our server, we have a type that identifies what is actually a pizza, like with an ID and a name, and then we can expose two endpoints, one for listing all the pizzas in the menu, and another one just creating a new pizza item in the menu. And in order to document our API and start generating our SDKs, we are going to use two tools.
The first one is called Swagger, which is a way of documenting RESTful APIs, and on top of that we're going to use the OpenAPI, which is actually a specification to do so. They work with different frameworks, different languages, they have too many clients that you can consume as well. And in order to do so, we are going to install two packages for our Fastify server, the first one is the Fastify Swagger module, and the other one is the UI that we want to bring up.
In order to bootstrap these two modules, the setup is pretty basic, so first we need to include the modules in our server, add some specification about the APIs, like a description, and then on the very last line we're going to take the output from the Swagger module and write it into our file system. So let's start describing our APIs.
First up, we have an ID, which is unique throughout our code base, and then we're going to use tags. We can use tags in order to separate different resources, APIs, and so on. And in order to describe our API, we have to actually describe just the response, because we have no parameters or query parameters, and so on. So our response is an object, and we are returning back an array of two of pizza menu items, which have an ID and a name as well. And last but not least, we have to actually include the schema into our route in our Fastify server.
In a similar manner, we're going to do the same for the creation endpoint, but this time we have to provide actually one parameter, which is the name of the pizza item. In a similar fashion, the response gets back that ID to the client. In the same manner as well, we're going to attach the schema into our route.
Once we have everything ready, this is the Fastify React UI, where you can have the full documentation about every single endpoint. You actually have smart defaults there. You can test the API in the browser, and so on. But you might be asking where React comes into that equation, right?
In order to generate our SDK, we are going to use Orval. Orval is an open source tool that takes up the OpenAVI specification and generates the SDK client. It works with different frameworks like Svelte, Vue, with different fetching libraries like SWR, and React Query as well. We have to install, globally or inside our project, the Orval SDK, and then we're going to run the Orval CLI using the OpenAVI specification as an input, and then targeting where we want our client to get generated.
In order to list... This is a pretty simple component that actually lists everything, lists all the pizza menu items. As you can see, the very first line is actually what got generated by Orval. And in a similar manner, we can create a really simple form.
3. Orval: Mutations, Testing, and Documentation
Short description:
Orval generates mutations and provides easy testing with mock service worker-generated mocks. You can use Zod for uniform validation in both backend and frontend. There are implementations for different languages and frameworks. You can consume APIs from various resources, including publicly available ones. The SDK can be committed to the source control system for tracking changes. Open API specifications can be used to generate documents with Swagger UI and Redux doc asserts. The code is available on my GitHub profile.
We have a mutation there. So Orval generates the mutation, and we can consume it inside our components as well. And you might be asking about testing. Orval takes that into the equation as well.
So out of the box, we have mock service worker-generated mocks. So it's pretty fairly easy to test everything as we need so. And there's more that you can actually do, because everything's like uniform. You can use Zod, for example, in order to provide uniform validation in your back-end and the front-end as well.
You don't have to stuck with Fastify, so you can use Rails or Next.js or Express, you name it. So there are like implementations in the ecosystem for so many languages and frameworks. You can actually consume APIs from different resources, even open publicly available APIs. Since everything gets committed, the SDK gets committed to our source control system, everything is in place so we can track down changes and so on. And last but not least, you can actually take that open API specification and generate your own documents and so on using the Swagger UI and Redux doc asserts and so on. The code is publicly available in my GitHub profile, so feel free to jump into, take a look how it works, maybe give me some comments and so on.
