Question: exposing OpenAPI can be used only with "contract first" approach?

[tresorama]

I started exploring this lib yesterday.
Firts, I implemented the server router a-la-trpc, skipping the creation of a contract, i call this approach code first.

Then I wanted to expose the server API with OpenAPI, so I started reading the docs.

The docs (https://orpc.unnoq.com/docs/openapi/getting-started#defining-routes) explain to add .route(...) to procedures.

// in backend server

export const listPlanet = os
  .route({ method: 'GET', path: '/planets' }) // ✅ this is new code
  .input(z.object({
    limit: z.number().int().min(1).max(100).optional(),
    cursor: z.number().int().min(0).default(0),
  }))
  .output(z.array(PlanetSchema))
  .handler(async ({ input }) => {
    // your list code here
    return [{ id: 1, name: 'name' }]
  })

// ...

With this change, I think that i can still use OpenAPI with an existing code-first approach.
But...
...when I reached the "client" creation docs (https://orpc.unnoq.com/docs/openapi/client/openapi-link#setup), the example, that replaces RPCLink of code-first approach with OpenAPILink requires a contract js object in the creation of the client.

// in a react spa app

import type { JsonifiedClient } from '@orpc/openapi-client'
import type { ContractRouterClient } from '@orpc/contract'
import { createORPCClient } from '@orpc/client'
import { OpenAPILink } from '@orpc/openapi-client/fetch'

import { contract } from '#backend/api/root-contract'   // ✅ this is new code

const link = new OpenAPILink(
  contract,  // ✅ this is new code
  {
    url: 'http://localhost:3000/api',
    headers: () => ({
      'x-api-key': 'my-api-key',
    }),
    // fetch: <-- polyfill fetch if needed
  }
)

const client: JsonifiedClient<ContractRouterClient<typeof contract>> = createORPCClient(link)

Obviously i don't want to expose server code into frontend so I don't want to do something like this

// in a react spa app

import type { JsonifiedClient } from '@orpc/openapi-client'
import type { ContractRouterClient } from '@orpc/contract'
import { createORPCClient } from '@orpc/client'
import { OpenAPILink } from '@orpc/openapi-client/fetch'

import { router } from '#backend/api/root-router'   // ✅ this is new code

const link = new OpenAPILink(
  router,  // ✅ this is new code
  {
    url: 'http://localhost:3000/api',
    headers: () => ({
      'x-api-key': 'my-api-key',
    }),
    // fetch: <-- polyfill fetch if needed
  }
)

Questions

Now I'm thinking that in order to expose the server router via OpenAPI it's mandatory to use a "contract first" approach.

1. Is it correct?
2. Any workaround?
3. If I want to keep using the code-first approach in the server, do I need to run a codegen/download step, to obtain a static file spec.json (a "client-safe" json object of the OpenAPI spec) that I can use when creating the "browser" client? Is the only way?

[unnoq]

You should migrate to "contract-first" or maybe (I'm not try yet) convert router into json and use it as a "contract"

[tresorama]

Thanks.

Is there a cli command for creating the router json automatically?

[unnoq]

@tresorama Not yet.