Generate OpenAPI REST endpoints

[tiagoefreitas]

Hi,
I am deciding between using tRPC new server actions (under development) or this, but I am inclined to tRPC because of trpc-openapi / package-trpc-swagger that automatically generate REST endpoints and OpenAPI specs when I need them.

What do you use for that, do you create them manually?

Thanks

[TheEdoRan]

I think tRPC is the better solution if you want that. next-safe-action is a simple type safe wrapper for React/Next Server Actions, so it's much lighter, since it doesn't have the router architecture that tRPC has. The API is (very) similar in v7, but under the hood there's much less library code. Hope this helps!

[crivera]

Hi - I am liking your project and hope to build a mini OpenAI Rest Endpoint - I have a lot already working just need the metadata, input and output schema from the action. My plan was to create a wrapper than can hold the information but I am having issues with the type. There are so many its kinda confusing :)

Any chance you could provide some ideas?

I have for example the following two action clients (on for anonymous access and one for authed)

export const actionClient = createSafeActionClient({
  handleServerError: (error) => {
    // in the middleware we always throw an ApiError, so we can catch it here and return the status code and message
    return {
      code: (error as ApiError).code,
      message: error.message
    }
  },
  defineMetadataSchema() {
    return z.object({
      name: z.string(),
      description: z.string().optional(),
      tags: z.array(z.string()),
      role: z.number()
    })
  }
})
  .use(async ({ next }) => {
    try {
      return await next()
    } catch (error) {
      if (error instanceof ApiError) {
        throw error
      }
      throw ApiError.fromError(error)
    }
  })
  .metadata({
    name: "Api Action",
    tags: [],
    role: Role.ANNONYMOUS,
    description: "Action that is part of the API"
  })

export const authedActionClient = actionClient
  .metadata({
    name: "Authed Action",
    tags: [],
    role: Role.USER,
    description: "Action that requires authentication"
  })
  .use(async ({ next }) => {
    const session = auth()

    if (!session || !session.userId) {
      throw new ApiError(403, "Session not found!")
    }

    const dbUser = await userStore.getByExternalId(session.userId)

    if (!dbUser) {
      throw new ApiError(403, "User not found.")
    }

    // Return the next middleware with `userId` value in the context
    return next({ ctx: { user: dbUser } })
  })

Now I am thinking of using a wrapper to build the rest api later but still want correct types:

This works - but the actionClient at the end has no more typing

export interface OpenAPIActionClientOpts {
  actionClient: SafeActionClient<??? DONT KNOW WHAT TO PUT HERE???>
  metadata?: ZodSchema
  inputSchema?: ZodSchema
  outputSchema?: ZodSchema
}

export function createOpenAPIActionClient(
    opts: OpenAPIActionClientOpts
  ) {
    const { actionClient, metadata, inputSchema, outputSchema } = opts
    let client = actionClient
  
    if (opts.metadata) {
      client = client.use(({ next, ctx, metadata }) => {
        return next({
          ctx: {
            ...ctx,
            metadata: {
              ...metadata,
              ...opts.metadata
            }
          }
        })
      })
    }
    if (opts.inputSchema) {
      client = client.schema(opts.inputSchema)
    }
    if (opts.outputSchema) {
      client = client.outputSchema(opts.outputSchema)
    }
    return {
      client,
      metadata,
      inputSchema,
      outputSchema
    }
}

and then the actual usage in the code would be

export const reindexRecipes = createOpenAPIActionClient({
      actionClient: adminActionClient,
      metadata: {
        name: "Reindex Recipes",
        role: Role.ADMIN,
        tags: ["Internal"],
        description:
          "Reindex all recipes in the current index. Should be only used internally. "
      },
      inputSchema: z.object({ delete: z.boolean().default(false) }),
      outputSchema: ActionResultDTO
    }).client.action(async ({ parsedInput }) => {
      const recipes = await recipeStore.getAll()
      if (parsedInput.delete) {
        await deleteIndex()
      }
      await bulkIndex(recipes.map((x) => mapToElasticDto(x)))
      return { success: true }
})

Let me know if this makes sense or if there is a better place to talk.

Thanks
Chris

[crivera]

also once it works I would love to contribute to the repo so that everyone can use it :)

[TheEdoRan]

@crivera First of all: sorry for the late reply. Second, this seems very hacky. Wouldn't it be better to build an OpenAPI middleware and pass OpenAPI metadata in metadata action method? Also, an OpenAPI client would be awesome, I agree, but at this time Server Actions should be only used for data mutations. React, though, rebranded them to "Server Functions" (Server Actions will be a subset of Functions), and they will be supposedly much more powerful than actions, right now you can't even access the request, for instance. So, in short, I'm thinking of building it, but I'm waiting for Server Functions (will probably change the library name too). If you're willing to help, I'm obviously open to contributions to improve the library, thank you! :)