notes.md

Q. When do we need OpenAPI spec ? Ans.

Q. Why and what does it provide? Consider a case where you have a nodejs express server and you desrcibe every end point of the express server in a single page of your nodejs express server. instead of writing all these you can describe a single page file like GET route Query Param -> id Returns { todo: { id: string, title: string, description: string, completed: boolean } }

Q. Why does a single page like this ? If you have a very long single route file then you can do the OpenAPI spec just like above one -

The things which it provides you is that ->

1. Auto generate documentation pages.
2. Auto generate client in various languages.
3. Let the world look at your API routes page without looking at your code base. This is not a security vulnerability cause you can already looked at the route of the website and the abckend which it is hitting.(Credentials will also be shared by them like JWT,cookies.)
4. Let AI's know how to hit your API in a single file withut sharing your code with the AI.

• The main thing about these files are they are very long file because they are the only routes which will be showed to the OpenAPI spec file and they will be very very long file. It will gve you an auto generated docs where every route is posted and where it will be hitting to what will be the response

Q. What is an OpenAPI Spec ? Ans. The OpenAPI Specification (OAS) is a standard, language-agnostic interface to RESTful APIs which allows both humans and computers to discover and understand the capabilities of a service without access to source code, additional documentation, or network traffic inspection. When properly defined via OpenAPI, a consumer can understand and interact with the remote service with minimal implementation logic.

• You never write the OpenAPI spec by your own hand , you auto generate it. The benefit of having a openapi spec file you can write it into yaml file and but if you are confused with this yaml format you can convert it into JSON also.

For this project we converted it into the json file cause the library which we are using is express so we need the JSON file for the express

The two things which we need to learn is that shcemas and the paths -> the paths are the routes of your application and schemas are all of the shape of your input and output extracted out which we can use.

Q. How to generate this file ? Ans. To generate this file if your language is very highly types file like rust/typescript it is very difficult for you to generate it from your hand but you can auto generate it.

• Slightly harder in golang and javascript.
• Node.js has some libraries/codebases that let you do it
• With express - https://www.npmjs.com/package/express-openapi (highly verbose)
• Without express - https://github.com/lukeautry/tsoa (Cohort 1 video)
• Hono has a native implementation with zod - https://hono.dev/snippets/zod-openapi

Now we will generate some openapi spec with the Hono, zod and openapi spec file ->

text -> Zod OpenAPI Hono is an extended Hono class that supports OpenAPI. With it, you can validate values and types using Zod and generate OpenAPI Swagger documentation. On this website, only basic usage is shown.

Q. What do you mean by minimal implementation logic ? It means automatically generating a client which writes the code for the representing of the logic to hit the endpoints of the openapi spec file has shown of the specific backend application.

You can use text this lib is going thru the spec.json file which will help you to generate the client automatically. (npx openapi-typescript-codegen --input ./spec.json --output ./generated) this is the command to generate the client autoatically.