Generate a Open API Spec File For The Backend

[rahulrana701]

Increasing Access

With the help of this feature, developers don't have to navigate through the entire codebase of the backend; they simply need to refer to this file to understand the routes and their functionalities. This can be immensely helpful in scenarios where a particular route or HTTP method is modified in the backend. Without this file, frontend developers or those unfamiliar with backend systems might inadvertently send requests to the wrong route or with incorrect methods, or they would have to delve into the extensive backend codebase.

However, with the aid of this file, any changes made to routes are instantly reflected in the OpenAPI file. Frontend developers or those without backend expertise can easily observe these changes in the OpenAPI file without needing to examine the backend codebase extensively. Consequently, they can adapt their approaches accordingly.

The OpenAPI file serves as a comprehensive repository of information about the routes, facilitating easy access and understanding of backend functionalities. Furthermore, this file can also be seamlessly integrated as a plugin in ChatGPT, further enhancing its utility and convenience.

This openapi file will be a single file having all the info about the routes, and this file can also be used as a plugin in chatgpt which is very useful.

Feature request details

I will create a open api spec file for our backend which will have details of all the routes.

[rahulrana701]

@lindapaiste @raclim I would like to work on this issue could you please assign it to me.

[lindapaiste]

Yes I think this would be really great! In the future we can use an OpenAPI file to automatically generate frontend code for making API calls. https://redux-toolkit.js.org/rtk-query/usage/code-generation

What sort of tools can we use for generating the openapi.json? Unfortunately we don't have the best typing or other documentation in the code right now, so I'm not sure how much of the process can be automated. I came across an article that describes a process which is very manual: https://www.freecodecamp.org/news/how-to-build-explicit-apis-with-openapi/. If we have to do all that then I would honestly not bother. I think we only want an Open API file if it can be generated automatically from JSDoc (or future TypeScript annotations).

[rahulrana701]

@lindapaiste Writing an OpenAPI file manually can be very time-consuming, so we will use a library called TSOA to generate an OpenAPI spec file for us.

[lindapaiste]

@lindapaiste Writing an OpenAPI file manually can be very time-consuming, so we will use a library called TSOA to generate an OpenAPI spec file for us.

Ok, so this is something that cannot be done until we convert the entire server-side codebase to Typescript, right?

[rahulrana701]

@lindapaiste Writing an OpenAPI file manually can be very time-consuming, so we will use a library called TSOA to generate an OpenAPI spec file for us.

Ok, so this is something that cannot be done until we convert the entire server-side codebase to Typescript, right?

Using the TSOA library, we need to write our code in TypeScript. However, there's no requirement to convert the entire server-side codebase to TypeScript; in fact, the server-side code remains unaffected. Instead, we'll create a separate folder for OpenAPI. We'll examine the schemas, routes, and their respective responses or return types, and then write them in our OpenAPI folder using the TSOA library. Afterward, we'll run a few commands, and it will generate an OpenAPI spec file by analyzing our code.

[lindapaiste]

@lindapaiste Writing an OpenAPI file manually can be very time-consuming, so we will use a library called TSOA to generate an OpenAPI spec file for us.

Ok, so this is something that cannot be done until we convert the entire server-side codebase to Typescript, right?

Using the TSOA library, we need to write our code in TypeScript. However, there's no requirement to convert the entire server-side codebase to TypeScript; in fact, the server-side code remains unaffected. Instead, we'll create a separate folder for OpenAPI. We'll examine the schemas, routes, and their respective responses or return types, and then write them in our OpenAPI folder using the TSOA library. Afterward, we'll run a few commands, and it will generate an OpenAPI spec file by analyzing our code.

Looking at the TSOA docs, it seems like the markup that they use to generate the OpenAPI comes from types, comments, and decorators that exist alongside the route controller code. In their examples they define the controllers using as classes rather than as collection of functions, but I don't know if that's actually a requirement. It definitely seems like TSOA code goes alongside the other code though?

Probably here: https://github.com/processing/p5.js-web-editor/blob/6cac275429c3911d87afdcdbbdbf185092aeac29/server/controllers/project.controller.js#L86

But possibly here: https://github.com/processing/p5.js-web-editor/blob/6cac275429c3911d87afdcdbbdbf185092aeac29/server/routes/project.routes.js#L15

Is where we would add the markup.

Maybe you can work on a draft PR as a proof of concept that applies this to one or two routes.

[rahulrana701]

@lindapaiste Even though TSOA utilizes classes, decorators, and other related constructs, underneath, the OpenAPI specification file that will be generated contains the HTTP routes. This means that TSOA operates using HTTP under the hood, and you won't see any decorators or classes reflected directly in the generated file. It's more of a behind-the-scenes mechanism for generating the file. I understand this might seem a bit unconventional, which is why I've created a separate folder specifically for this purpose. If you'd like, I can certainly submit a draft PR for the scenario mentioned above.