Forem: Muhammad Bima Adi Prabowo

Writing Python code like Typescript

Muhammad Bima Adi Prabowo — Thu, 01 Aug 2024 02:31:03 +0000

I assume you guys who want to read this article know what typescript is. Javascript developer created typescript to make javascript more typesafe. Typesafe make code more readable and has less bug without writting any test. Can typesafety be achieve in python?.

Why we need typesafety?

Imagine this innocent looking function



def send_email(sender, receiver, message):
    ...

I intentionally hide it's code implementation. Can you guess what is function for and what parameter that we need in order to use this function by just it's function name and parameter?. We know from it's function name it's function for sending an email. What about it's parameter, what should we put in order to use this function?.

First guess sender is str of email, receiver is str of email, message is str of body of an email.



send_email(sender="john@mail.com", receiver="doe@mail.com", message="Hello doe! How are you?")

Most simple guess. but it's not the only guess.

Second guess sender is int of user_id on db, receiver is int of user_id on db, message is str of body of an email.



john_user_id = 1
doe_user_id = 2
send_email(sender=1, receiver=2, message="Hello doe! How are you?")

Imagine working on aplication. Most aplication use some database. User usualy represent by it's id.

Third guess sender is dictionary, receiver is dictionary, message is dictionary.



john = {
    "id": 1,
    "username": "john",
    "email": "john@mail.com"
}
doe = {
    "id": 2,
    "username": "doe",
    "email": "doe@mail.com"
}
message = {
    "title": "Greeting my friend doe",
    "body": "Hello doe! How are you?"
}
send_email(sender=john, receiver=doe, message=message)

Maybe send_email need more than email and user id. To add more data on each parameter it's used some dictionary structure. You notice that message it's not just str maybe it's need title and body.

Forth guess sender is class User, receiver is class User, message is dictionary.



class User():

    def __init__(self, id, username, email):
        self.id = id
        self.username = username
        self.email = email

john = User(id=1, username="john", email="john@mail.com")
doe = User(id=2, username="doe", email="doe@mail.com")
message = {
    "title": "Greeting my friend doe",
    "body": "Hello doe! How are you?"
}
send_email(sender=john, receiver=doe, message=message)

Maybe send_email integrate with some database orm like Django ORM or Sqlalchemy. In order to make it easier for end user, it's used ORM class directly.

So which one is the correct answer? one of them can be a correct answer. Maybe the correct answer can be combination of two guess. Like sender and receiver is class User (Forth guess) but message it's str (First guess). We cannot sure unless we read it's code implementation. Which is waste of time if you an end user. As an end user who use this function we just need what function do, what parameter that it's need and what function output is.

The Solution

Docstring

Python has built in fuction documentation using docstring. Here docstring example.



def add(x, y):
    """Add two number

    Parameter:\n
    x -- int\n
    y -- int\n

    Return: int
    """
    return x + y

def send_email(sender, receiver, message):
    """Send email from sender to receiver

    Parameter:\n
    sender -- email sender, class User\n
    receiver -- email receiver, class User\n
    message -- body of the email, dictionary (ex: {"title": "some title", "body": "email body"}\n

    Return: None
    """
    ...

What's cool about docstring it's editor compatible. In vscode it will shown docstring when you hover over a function. Most library in python use docstring to document it's function.

The problem with docstring is document syncronization. How you make sure that the docstring always sync with code implementation. You cannot put it on test right. I hear that from random person on the internet "Having outdated documentation is worse than having no documentation".

Doctest

Btw You can test docstring using doctest kinda. Doctest testing your docstring by running example on your docstring. Doctest is already preinstalled in python so you don't need external depedencies. let's see this example create new file called my_math.py then put this code.



# my_math.py
def add(x, y):
    """Add two integer

    Parameter:\n
    x -- int\n
    y -- int\n

    Return: int
    >>> add(1, 2)
    3
    """
    return x + y


if __name__ == "__main__":
    import doctest

    doctest.testmod()

It's same code like docstring example but I add example and doctest at last line of the code. In order to test the docstring just run the file python my_math.py. If theres no output it's mean your example pass the test. If you want see the output run it in verbose mode python my_math.py -v, you'll see this output.



Trying:
    add(1, 2)
Expecting:
    3
ok
1 items had no tests:
    __main__
1 items passed all tests:
   1 tests in __main__.add
1 tests in 2 items.
1 passed and 0 failed.
Test passed

If you make mistake on code example it will return an error.



# my_math.py
def add(x, y):
    """Add two integer

    Parameter:\n
    x -- int\n
    y -- int\n

    Return: int
    >>> add(2, 2) # <-- I change it here
    3
    """
    return x + y


if __name__ == "__main__":
    import doctest

    doctest.testmod()

the output:



**********************************************************************
File "~/typescript-in-python/my_math.py", line 12, in __main__.add
Failed example:
    add(2, 2) # <-- I change it here
Expected:
    3
Got:
    4
**********************************************************************
1 items had failures:
   1 of   1 in __main__.add
***Test Failed*** 1 failures.

Great! now I can test my docstring. But the caveats are:

doctest only check the example it doesn't check comment function parameter and return
doctest need to run the code like other testing tools in order to check it is correct or not doctest need to run the code example. If your code need some external tools like database or smtp server (like sending an email) it's hard to test using doctest.

Python typing

Sometimes you don't need to run the code to check is code correct or not. You just need input type and output type. How? Consider this example.



def add(x, y):
    """Add two integer

    Parameter:\n
    x -- int\n
    y -- int\n

    Return: int
    """
    return x + y

def sub(x, y):
    """Substract two integer

    Parameter:\n
    x -- int\n
    y -- int\n

    Return: int
    """
    return x - y

a = add(2, 1)
b = add(1, 1)
c = sub(a, b)

function add return an int and function sub need two int as input paramter. If I use two return from add function then put it on sub paramater like example above will it error? of course not because sub function need int and you put an int as well.

Since python 3.5 python have built in type called typing. With typing you can add type on your function like example below.



def add(x: int, y: int) -> int:
    """Add two integer"""
    return x + y

a = add(1, 2)

Instead put it on your docstring you put it on the function. Typing is supported on many editor. If you use vscode you can hover on variable and it will shown it's type.

Nice now our code will have a type safety. eeehhhh not realy. If I intentionally use function incorrectlly like this.



def add(x: int, y: int) -> int:
    """Add two integer"""
    return x + y

res = add(1, [])
print(res)

It will show error



Traceback (most recent call last):
  File "~/typescript-in-python/main.py", line 5, in <module>
    res = add(1, [])
          ^^^^^^^^^^
  File "~/typescript-in-python/main.py", line 3, in add
    return x + y
           ~~^~~
TypeError: unsupported operand type(s) for +: 'int' and 'list'

But it doesn't show that you put incorrect type. Even worse if you use it like this.



def add(x: int, y: int) -> int:
    """Add two integer"""
    return x + y

res = add("hello", "world")
print(res)

It will succeed. It must be error because you put incorrect type.



helloworld

Why python typing doesn't have type checker by default??. Based on pep-3107 it said

Before launching into a discussion of the precise ins and outs of Python 3.0’s function annotations, let’s first talk broadly about what annotations are and are not:

Function annotations, both for parameters and return values, are completely optional.

Function annotations are nothing more than a way of associating arbitrary Python expressions with various parts of a function at compile-time. By itself, Python does not attach any particular meaning or significance to annotations. Left to its own, Python simply makes these expressions available as described in Accessing Function Annotations below.

The only way that annotations take on meaning is when they are interpreted by third-party libraries. ...

So in python typing is like a decorator in typescript or java it doesn't mean anything. You need third party libraries todo type checking. Let's see some library for typechecking.

Python typing + type checker

Here are libraries for typechecking in python. For example we will typecheck this wrong.py file



def add(x: int, y: int) -> int:
    """Add two integer"""
    return x + y

res = add("hello", "world")
print(res)

1.mypy

The "OG" of python type checker. To install it just using pip pip install mypy. Now let's use mypy to typecheck this file. Run mypy wrong.py. It will shown type error which is nice.



wrong.py:5: error: Argument 1 to "add" has incompatible type "str"; expected "int"  [arg-type]
wrong.py:5: error: Argument 2 to "add" has incompatible type "str"; expected "int"  [arg-type]
Found 2 errors in 1 file (checked 1 source file)

btw you can run mypy on entire project by using mypy ..

2.pyright

Another typechecker is pyright. It created by microsoft. It's same like mypy install through pip pip install pyright. Then run it pyright wrong.py. It will shown this error.



~/typescript-in-python/wrong.py
  ~/typescript-in-python/wrong.py:5:11 - error: Argument of type "Literal['hello']" cannot be assigned to parameter "x" of type "int" in function "add"
    "Literal['hello']" is incompatible with "int" (reportArgumentType)
  ~/typescript-in-python/wrong.py:5:20 - error: Argument of type "Literal['world']" cannot be assigned to parameter "y" of type "int" in function "add"
    "Literal['world']" is incompatible with "int" (reportArgumentType)
2 errors, 0 warnings, 0 informations

It said that it's more faster than mypy but I found that's not much diffrent. Maybe my code base it's to small. Also pyright implement more python standard than mypy you can see on https://microsoft.github.io/pyright/#/mypy-comparison. Personaly I prefer mypy than pyright because the error message were more readable.

3.pylyzer

Speaking of performance and speed another new python typechecker pylyzer. It's written in rust. You can install it through pip pip install pylyzer or through cargo (rust package manager) cargo install pylyzer --locked. Then run it pylyzer wrong.py. It will shown this error.



Start checking: wrong.py
Found 2 errors: wrong.py
Error[#2258]: File wrong.py, line 5, <module>.res

5 | res = add("hello", "world")
  :           -------
  :                 |- expected: Int
  :                 `- but found: {"hello"}

TypeError: the type of add::x (the 1st argument) is mismatched

Error[#2258]: File wrong.py, line 5, <module>.res

5 | res = add("hello", "world")
  :                    -------
  :                          |- expected: Int
  :                          `- but found: {"world"}

TypeError: the type of add::y (the 2nd argument) is mismatched

So far this is the most readable and beautiful error message. It's reminds me of rust compiler error. Speed, performance and most readable error message, I think I will choose to using pylyzer if the package already stable. The problem is at the time I write this blog, pylyzer still in beta. It can only typecheck your code base, it haven't support external depedencies.

Conclusion

Alright we successfully write python code like typescript (kinda). There is more way to using python typing module other than check simple type (str, int, bool etc). Maybe I will cover more advance type it in next blog. Maybe you guys have opinion about this, know better typechecker other then those 3, found other way to do typecheck in python or other. let me know on comment section below. As always Happy Coding.

Make Maintainable Python Project

Muhammad Bima Adi Prabowo — Sun, 02 Jun 2024 03:49:37 +0000

Imagine you have personal python project several months ago. You try to re run it on your pc but it not work. You face some error like missing depedencies, incompatible python version etc. It take a day to solve that issue. Imagine if this in your day job. Your python project must work on production server and your
college pc as well. Facing this issue over and over is not productive.

In this blog I will show you how to eleminate this problem to make your python project maintainable. Using some common python project best practice.

1. Define your python version

Every python depedencies has diffrent python version requirement. For example python 2.7 (who still use python 2.7 in 2024??) it can only work with django version 1.8. Fastapi need minimum python 3.5 because feature typehint first introduce on python 3.5.

Where should I define python version? personally I put it on README.md. I create section called requirement then I put it on their. You can see on this github repo https://github.com/BimaAdi/Make-Maintainable-Python-Project.

2. Using virtual environtment

By default when using pip if you do pip install {some package} it will store globaly and will be available to all your project.The problem is not all your project use that all depedencies. For example you have multiple project one about machine learning and other about backend development.Machine learning project use some machine learning related package such as numpy, pandas, scikit learn etc while backend project use some backend related packagesuch as Django. Your machine learning project doesn't need django and neither your backend project doesn't need numpy nor scikit learn. By using virtual environtment you
encapsulated depedencies for every project.

To create virtual environtment on your project folder run command:

python -m venv env

On your project folder you will see an env folder. This folder will store your python intepreter and python depedencies. To use your newly created environtment you can use command:

linux and macos (bash or zsh)

source env/bin/activate

windows (command promt)

env\Scripts\activate.bat

windows (powershell)

env\Scripts\activate.ps1

After run that command you notice that your terminal/command promt/powershell have (env) on the left side.

This mark that you no longer use your global python intepreter, but you use python intepreter on your env folder. If you perform pip list you also notice that you don't have any package depedencies.

When you perform pip install {some package} while you have (env) you will store it on your env folder. Try pip install Faker pandas then pip list you will see that it installed on your env folder.

To use my global python intepreter back. You can create new terminal/command promt/powershell or you deactivate the environtment using command deactivate. Don't push env folder to git repository. Make sure to add env folder to your .gitignore.

3. Note your project depedencies using requirements.txt

When your project grow larger you need more depedencies. Install all depedencies manualy is not efective. You also need to define what version your python depedencies need. To solve that problem we can use requirements.txt. requirements.txt it just a txt file that store your python depedencies.
To generate that file on terminal while you using virtual environtment run command pip freeze > requirements.txt. pip freeze will print all depedencies and it's version in your virtual environtment on terminal while > requirements.txt to put output on requirements.txt.

After you run that file you notice new file requirements.txt. To reinstall python depedencies you just need run command pip install -r requirements.txt. Make sure whenever you add new depedencies to your
project update your requirements.txt using pip freeze > requirements.txt.

To make it more clear I have some code example that generate fake user data then stored in csv that use all these tips. You can see it from this github repo
https://github.com/BimaAdi/Make-Maintainable-Python-Project

That's all guys there are still more tips to make maintainable python project such as project structure, using testing, formater, etc, But I want to scope it just to python specific project, general and as minimal as possible. If you have more tips or you have diffrent opinion you can add it on comment section below. Cheers.

Membuat Project Python yang mudah untuk dimaintain

Muhammad Bima Adi Prabowo — Sun, 02 Jun 2024 03:48:05 +0000

Bayangkan kamu memiliki project python pribadi di github kamu yang sudah tidak kamu buka selama berbulan-bulan. Ketika dicoba di laptop kamu ternyata tidak jalan entah karena kurang depedencies atau versi python kamu tidak cocok dan lain-lain. Seharian kamu berusaha menyelesaikan masalah tersebut dan akhirnya project tersebut bisa berjalan dilaptop kamu. Sekarang bayangkan jika hal tersebut terjadi di kantormu. Program itu selain harus bisa jalan di laptop kamu tetapi harus bisa jalan juga di server dan laptop teman kerja. Menyelesaikan masalah ini berulang-ulang itu tidak produktif.

Pada blog ini saya akan memberikan tips dan trik untuk membuat project python kalian lebih mudah dimaintain. Menggunakan best practice di python.

1. Definisikan versi python yang digunakan

Setiap depedencies python memiliki minimum versi python tersendiri. Contohnya Django 1.8 cuma bisa diggunakan oleh python 2.7 (Siapa yang masih pake python 2.7 di 2024??). Untuk menggunakan fastapi minimum versinya adalah python 3.5 karena fitur typehint pertama kali dikenalkan di pyhton 3.5.

Dimana saya harus mendefinisikan versi python yang digunakan? Saya pribadi mendifinisikan versi python di README.md. Saya membuat satu bagian yang berjudul requirement lalu mendefinisikanya di bagian tersebut. Contohnya bisa kalian lihat di repository github berikut https://github.com/BimaAdi/Make-Maintainable-Python-Project.

2. Menggunakan Virtual Environtment

Secara default ketika menggunakan pip ketika kita melakukan pip install {nama package} pip akan menyimpan depedency secara global jadi bisa diakses oleh semua project di laptop kita. Masalahnya adalah tidak semua project menggunakan depedency tersebut. Contohnya kamu memiliki 2 project satu project mengenai machine learning satu lagi project mengenai backend development. Project machine learning menggunakan depedency yang berhubungan dengan machine learning seperti numpy, pandas, scikit learn dan lain-lain, Sedangkan project backend development menggunakan web framework seperti django. Project machine learning tidak membutuhkan django begitu pula project backend development tidak membutuhkan numpy, pandas maupun scikit learn. Dengan menggunakan virtual environtment kita mengelompokan depedencies berdasarkan kebutuhan project-project kita.

Untuk membuat virtual environtment pada folder project jalankan perintah:

python -m venv env

Pada folder project kalian akan melihat satu folder baru yang namanya env/. Folder ini menyimpan python intepreter dan depedency python. Untuk menggunakan python pada folder env jalankan perintah:

linux dan macos (bash or zsh)

source env/bin/activate

windows (command promt)

env\Scripts\activate.bat

windows (powershell)

env\Scripts\activate.ps1

Setelah menjalankan perintah diatas pada tampilan kiri terminal/command promt/powershell terdapat icon (env).

Ini menandakan python yang digunakan adalah python yang terdapat pada folder env (virtual environtmet) bukan python yang terinstalasi secara global. Kalau kalian coba jalankan perintah pip list tidak ada depedency apa pun kecuali bawaan python kalian.

Kalau kalian jalankan pip install {nama depedency} ketika terdapa icon (env) maka depedency tersebut akan disimpan di folder env. Coba lakukan pip install Faker pandas lalu pip list depedencies akan tersimpan di folder env.

Untuk menggunakan python intepreter global bisa dengan 2 cara. Cara yang pertama dengan membukan terminal/command promt/powershell baru. Cara kedua dengan mematikan environtmentnya menggunakan perintah deactivate.

Pastikan folder env tidak masuk ke git repository jika menggunakan git. tambahkan folder env pada file .gitignore.

3. Catat depedency project pada file requirements.txt

Semakin besar suatu project semakin banyak depedency yang dibutuhkan. Mengintall depedency satu per satu pasti akan memakan banyak waktu. Selain itu kita juga harus mendefinisikan versi depedency apa yang digunkan. Untuk menyelesaikan masalah tersebut bisa menggunakan requirements.txt. requirements.txt itu hanya file txt biasa yang menyimpan depedency python dan versi yang digunakan.

Untuk membuat file requirements.txt ketika dalam kondisi menjalankan virtual environtment jalankan perintah pip freeze > requirements.txt. Perintah pip freeze menampilkan semua depedencies dan versinya pada virtual environtment. Perintah > requirements.txt untuk menyimpan hasilnya pada file requirements.txt.

Agar lebih jelas. Saya memiliki contoh project yang menggunakan semua tips diatas. Kalian bisa melihatnya di repository github https://github.com/BimaAdi/Make-Maintainable-Python-Project

Sebenarnya masih banyak tips lain untuk memmpermudah memaintain project python seperti menggunakan testing, formater dan lain-lain. Namun pada blog ini saya ingin specific hanya di python dan seminimal mungkin. Jika kalian memiliki tips lain atau solusi lain silahkan ditambah di kolom komentar.

Integrate Hono with Openapi/Swagger

Muhammad Bima Adi Prabowo — Tue, 23 Jan 2024 02:19:07 +0000

I like to write web application using typescript, Because of typesafety. You can make sure what api your frontend call it's suitable with what your backend serve. Library like TRPC prove that it can be done. Moreover typescript(javascript) not only can build web application, it can also build mobile app (react native) and desktop (electron, tauri, wails), so you can apply typesafety on different client as well.

But not everything were written in typescript. For example you have a mobile developer who write app in Native language (Kotlin, Java, Swift) or using different framework like Flutter. Maybe you want to create webhook so you cannot use specific language feature.

One of standard that integrate "typesafety" accross programing language is openapi(swagger). In this tutorial we will integrate Hono webframework with Openapi.

Requirement and Installation

Requirement

Node >= 20
npm or yarn or pnpm

Instalation

we gonna use hono nodejs quick start template hono quickstart



npm create hono@latest
// or
yarn create hono
// or
pnpm create hono

for target directory I will named it hono-openapi then choose nodejs as template.

Go to target directory then Install depedencies.



npm install
# or 
yarn install
# or
pnpm install

Setup Openapi and Swagger

1.Add depedencies for openapi and swagger



npm install zod @hono/zod-openapi @hono/swagger-ui
# or 
yarn install zod @hono/zod-openapi @hono/swagger-ui
# or
pnpm install zod @hono/zod-openapi @hono/swagger-ui

2.Replace src/index.ts



import { serve } from "@hono/node-server";
import { swaggerUI } from "@hono/swagger-ui";
import { OpenAPIHono } from "@hono/zod-openapi";

const app = new OpenAPIHono();

// The openapi.json will be available at /doc
app.doc("/doc", {
    openapi: "3.0.0",
    info: {
        version: "1.0.0",
        title: "My API",
    },
});

// swagger ui doc will be available at {server url}/ui
// fell free to change the url
// swaggerUI url must have same path as openapi.json
app.get("/ui", swaggerUI({ url: "/doc" }));

const port = 3000;
console.log(`Server is running on port ${port}`);

serve({
    fetch: app.fetch,
    port,
});

3.Run server



npm run dev
# or 
yarn dev
# or
pnpm run dev

4.Your swagger doc will be available at http://localhost:3000/ui

Basic Route

let's create hello world route, a simple route that just return json with key "hello" and value "world".



import { serve } from "@hono/node-server";
import { swaggerUI } from "@hono/swagger-ui";
import { OpenAPIHono, createRoute } from "@hono/zod-openapi"; // <- add createRoute
import { z } from "zod"; // <- add zod

const app = new OpenAPIHono();

// The openapi.json will be available at /doc
app.doc("/doc", {
    openapi: "3.0.0",
    info: {
        version: "1.0.0",
        title: "My API",
    },
});

// basic route
// ------ added code -------
const basicRoute = createRoute({
    method: "get",
    path: "/basic/",
    responses: {
        200: {
            content: {
                "application/json": {
                    schema: z.object({
                        hello: z.string(),
                    }),
                },
            },
            description: "say hello",
        },
    },
});

app.openapi(basicRoute, (c) => {
    return c.json({ hello: "world" }, 200);
});
// ------ end added code -------

// swagger ui doc will be available at {server url}/ui
// fell free to change the url
// swaggerUI url must have same path as openapi.json
app.get("/ui", swaggerUI({ url: "/doc" }));

const port = 3000;
console.log(`Server is running on port ${port}`);

serve({
    fetch: app.fetch,
    port,
});

app.openapi receive 2 parameter schema and route. schema is where you put your openapi definition while route is basic hono api route. Route documentation will shown at swagger UI below.

Code Spliting

When your app grow larger, You don't want all your route in index.ts. You want to split it in other file or folder. This is how you split route on diffrent file. Create file foo.ts then add this code.



// src/foo.ts
import { OpenAPIHono, createRoute } from "@hono/zod-openapi";
import { z } from "zod";

export const app = new OpenAPIHono();

const fooRoute = createRoute({
    method: "get",
    path: "/other/",
    responses: {
        200: {
            content: {
                "application/json": {
                    schema: z.object({
                        foo: z.string(),
                    }),
                },
            },
            description: "foo response",
        },
    },
    tags: ["Foo"], // <- Add tag here
});

app.openapi(fooRoute, (c) => {
    return c.json({ foo: "hello foo" }, 200);
});

then import it on your index.ts.



// src/index.ts
import { serve } from "@hono/node-server";
import { swaggerUI } from "@hono/swagger-ui";
import { OpenAPIHono, createRoute } from "@hono/zod-openapi";
import { z } from "zod";
import { app as appFoo } from "./foo"; // <- import route here

const app = new OpenAPIHono();
app.route("/foo", appFoo); // <- add imported route here

// The openapi.json will be available at /doc
app.doc("/doc", {
    openapi: "3.0.0",
    info: {
        version: "1.0.0",
        title: "My API",
    },
});

// rest of code
// ...

It will shown add your swagger UI like this.

all imported route will be prefixed with "/foo".

Cheat sheat

These are some use case example:

Path and Query

Params and query can only be string. If it's not string hono will return never on c.req.valid("query"). If you want type other than string add key type, then do parsing and validation on route.



const pathAndQueryRoute = createRoute({
    method: "get",
    path: "/path-and-query/{id}",
    request: {
        query: z.object({
            a: z.string().openapi({
                param: {
                    name: "a",
                    in: "query",
                },
                type: "integer",
                example: "1",
            }),
            b: z
                .string()
                .optional()
                .openapi({
                    param: {
                        name: "b",
                        in: "query",
                        required: false,
                    },
                    type: "integer",
                    example: "2",
                }),
        }),
        params: z.object({
            id: z.string().openapi({
                param: {
                    name: "id",
                    in: "path",
                },
                type: "integer", // <- you can still add type by adding key type
                example: "1",
            }),
        }),
    },
    responses: {
        200: {
            content: {
                "application/json": {
                    schema: z.object({
                        id: z.string(),
                        a: z.string(),
                        b: z.string().nullable().optional(),
                    }),
                },
            },
            description: "Ok Response",
        },
    },
});

app.openapi(pathAndQueryRoute, (c) => {
    const { id } = c.req.valid("param");
    const { a, b } = c.req.valid("query");
    return c.json({ id, a, b: b || null }, 200);
});

Form Data



const formDataRoute = createRoute({
    method: "post",
    path: "/form-data/",
    request: {
        body: {
            content: {
                "multipart/form-data": {
                    schema: z
                        .object({
                            foo: z.string(),
                            bar: z.string(),
                            image: z.instanceof(File).or(z.string()).openapi({
                                type: "string",
                                format: "binary",
                            }),
                        })
                        .openapi({
                            required: ["foo"],
                        }),
                },
            },
        },
    },
    responses: {
        200: {
            content: {
                "application/json": {
                    schema: z.object({
                        foo: z.string(),
                        bar: z.string().nullable(),
                        image: z.string().nullable(),
                    }),
                },
            },
            description: "form data ok response",
        },
    },
});

app.openapi(formDataRoute, (c) => {
    const { foo, bar, image } = c.req.valid("form");

    if (image instanceof File) {
        // save file code here
    }

    return c.json(
        {
            foo,
            bar,
            image: image instanceof File ? image.name : null,
        },
        200,
    );
});

Form Data Multiple



const formMultipleRoute = createRoute({
    method: "post",
    path: "/form-data-multiple/",
    request: {
        body: {
            content: {
                "multipart/form-data": {
                    schema: z.object({
                        arrStr: z.string().openapi({
                            type: "array",
                            items: {
                                type: "string",
                            },
                        }),
                        arrFile: z
                            .instanceof(File)
                            .or(z.string())
                            .openapi({
                                type: "array",
                                items: {
                                    type: "string",
                                    format: "binary",
                                },
                            }),
                    }),
                },
            },
        },
    },
    responses: {
        200: {
            content: {
                "application/json": {
                    schema: z.object({
                        arrStr: z.array(z.string()),
                        arrFile: z.array(z.string()),
                    }),
                },
            },
            description: "form data ok response",
        },
    },
});

app.openapi(formMultipleRoute, async (c) => {
    // c.req.valid not working on array form
    const formData = await c.req.formData();

    // Get array string
    const strs = formData.getAll("arrStr");
    const arrStr: string[] = [];
    for (const item of strs) {
        if (typeof item === "string") {
            arrStr.push(item);
        }
    }

    // Get array file
    const files = formData.getAll("arrFile");
    const arrFile: string[] = [];
    for (const file of files) {
        if (file instanceof File) {
            // save file code here
            arrFile.push(file.name);
        }
    }

    return c.json(
        {
            arrStr,
            arrFile,
        },
        200,
    );
});

Download File



import path = require("node:path");
import { readFileSync } from "node:fs";

const downloadFileRoute = createRoute({
    method: "get",
    path: "/download-file/",
    summary: "download file",
    request: {
        query: z.object({
            contentType: z
                .union([z.literal("image/png"), z.literal("application/octet-stream")])
                .default("image/png"),
        }),
    },
    responses: {
        200: {
            content: {
                "image/png": {
                    schema: z.any().openapi({
                        type: "object",
                        format: "binary",
                    }),
                },
                "application/octet-stream": {
                    schema: z.any().openapi({
                        type: "object",
                        format: "binary",
                    }),
                },
            },
            description:
                "Return file, contentType can be image/png or application/octet-stream",
        },
    },
});

// disable ts check because hono openapi cannot validate raw response
// @ts-ignore: Unreachable code error
app.openapi(downloadFileRoute, async (c) => {
    const { contentType } = await c.req.valid("query");
    const payload = readFileSync(path.join("static", "Wikipedia-logo.png"));
    if (contentType === "image/png") {
        return new Response(payload, {
            headers: {
                "content-type": "image/png",
            },
            status: 200,
        });
    } else {
        return new Response(payload, {
            headers: {
                "content-type": "application/octet-stream",
                "Content-Disposition": 'attachment; filename="wikipedia.png"',
            },
            status: 200,
        });
    }
});

Security (Authorization Api Key)



// Register security scheme
// add it on your index.ts
app.openAPIRegistry.registerComponent(
    "securitySchemes",
    "AuthorizationApiKey", // <- Add security name
    {
        type: "apiKey",
        name: "X-API-KEY",
        in: "header",
    },
);

const protectedApiKeyRoute = createRoute({
    method: "get",
    path: "/protected-api-key/",
    summary: "Protected api-key Example",
    security: [
        {
            AuthorizationApiKey: [], // <- Add security name (must be same)
        },
    ],
    request: {
        headers: z.object({
            "x-api-key": z.string().optional(),
        }),
    },
    responses: {
        200: {
            content: {
                "application/json": {
                    schema: z.object({
                        message: z.string(),
                    }),
                },
            },
            description: "Authorized Response",
        },
        401: {
            content: {
                "application/json": {
                    schema: z.object({
                        error: z.string(),
                    }),
                },
            },
            description: "Unauthorized Response",
        },
    },
    tags: ["Examples"],
});

app.openapi(protectedApiKeyRoute, (c) => {
    const { "x-api-key": apiKey } = c.req.valid("header");
    // or
    console.log(c.req.header()["x-api-key"]);
    if (apiKey) {
        return c.json(
            {
                message: "Hello",
            },
            200,
        );
    }
    return c.json(
        {
            error: "Unauthorized",
        },
        401,
    );
});

Security (Bearer)



// Security (Bearer)
// Register security scheme
// add it on your index.ts
app.openAPIRegistry.registerComponent(
    "securitySchemes",
    "AuthorizationBearer", // <- Add security name
    {
        type: "http",
        scheme: "bearer",
        bearerFormat: "JWT",
    },
);

export const protectedBearerRoute = createRoute({
    method: "get",
    path: "/protected-bearer/",
    summary: "Protected bearer Route Example",
    security: [
        {
            AuthorizationBearer: [], // <- Add security name (must be same)
        },
    ],
    request: {
        headers: z.object({
            authorization: z.string().optional(),
        }),
    },
    responses: {
        200: {
            content: {
                "application/json": {
                    schema: z.object({
                        message: z.string(),
                    }),
                },
            },
            description: "Authorized Response",
        },
        401: {
            content: {
                "application/json": {
                    schema: z.object({
                        error: z.string(),
                    }),
                },
            },
            description: "Unauthorized Response",
        },
    },
});

app.openapi(protectedBearerRoute, (c) => {
    const { authorization } = c.req.valid("header");
    // or
    console.log(c.req.header()["authorization"]);
    if (authorization) {
        return c.json(
            {
                message: "Hello",
            },
            200,
        );
    }
    return c.json(
        {
            error: "Unauthorized",
        },
        401,
    );
});

That's all guys. Full source code are availble on github repo https://github.com/BimaAdi/Integrate-hono-with-openapi. I hope it can help you integrate hono with openapi/swagger. If I found something new, incorrect or out of date, I'll try to revised this post. If you have any question or found something wrong feel free to ask on the comment section. Cheers.