I built an API with Hono + OpenAPI recently. I wanted the contract between server and client to be honest. And it surprised me how much that changes things.

The problem with APIs today

I write an endpoint. I write documentation (which inevitably gets out of sync). The client writes types by hand (or copy-pastes from the docs). I change a field. Docs don't update. Client still uses old types. Everything fails silently in production.

The problem isn't technical. It's that there's no honesty. My code is the truth. Documentation is a well-meaning lie. Client types are fiction.

OpenAPI is honesty

When you use OpenAPI in Hono, the contract lives in your code. It's not a separate document. It's reality.

const querySchema = v.object({
  name: v.optional(v.string()),
})

const responseSchema = v.string()

This isn't documentation. It's your server saying explicitly: "a greeting has an optional name". If someone tries to pass something else, you reject it. Validation is automatic.

app.get(
  '/',
  describeRoute({
    description: 'Say hello to user',
    responses: {
      200: {
        description: 'Greeting response',
        content: { 'text/plain': { schema: resolver(responseSchema) } }
      }
    }
  }),
  validator('query', querySchema),
  (c) => {
    const query = c.req.valid('query')
    return c.text(`Hello ${query?.name ?? 'World'}!`)
  }
)

Here's the shift: you describe the route once. Hono validates. It generates the OpenAPI spec. It documents. All from the same code.

I'm not writing documentation. I'm describing server reality. That's different.

One endpoint exposes everything

app.get('/openapi', openAPIRouteHandler(app, {
  documentation: {
    info: {
      title: 'My API',
      version: '1.0.0'
    }
  }
}))

One endpoint. Your entire API contract. Clients read it. Swagger UI renders it. Everything knows the truth.

For me, OpenAPI is about removing lies. When your validation is the source of truth, and your docs flow from it, there's no gap. No confusion.

Your clients don't wonder "does this work?". They know it works. Their IDE knows. The compiler knows. It's certainty.

Taste in design

Writing honest APIs means other developers read your code and instantly understand what you expect, what you return, why you reject invalid input.

It's not about rules. It's not about "best practices". It's about letting your code be clear. Accessible. Honest.

That requires taste. And taste is personal.

Why it matters

Building APIs that developers want to use is hard. It's easier to build APIs that work. But working ≠ usable.

OpenAPI in Hono doesn't force you to have good taste. But it lets you express it. It lets you be honest about what your API is and what it does.

And that's what matters.