What your backend needs

• OpenAPI 3.0 or 3.1, as JSON or YAML. Swagger 2.0 is rejected with a clear error.
• tags on operations. The first tag is the group: user.posts.create(…). Without tags the group comes from the operationId prefix, then the path.
• A test mode. Tests need to start from a known state and finish flows without real email or SMS:
  • an endpoint that resets data (only in test mode);
  • predictable confirmation codes;
  • no real emails or SMS.

Test mode in the Nest example

main.ts and app.module.ts mount POST /test/reset only when TEST_MODE=1:

main.ts

const TEST_MODE = process.env.TEST_MODE === '1'

const app = await NestFactory.create(AppModule.register({ testMode: TEST_MODE }))

app.module.ts

/** `testMode` mounts `TestController` (`POST /test/reset`). */
static register({ testMode }: { testMode: boolean }): DynamicModule {
  return {
    module: AppModule,
    controllers: [
      AuthController,
      PostsController,
      CommentsController,
      UsersController,
      ...(testMode ? [TestController] : []),
    ],
    providers: [Store, AuthGuard],
  }
}

Recipes

NestJS

By default Nest names operations PostsController_create. An operationIdFactory gives posts.create (openapi.ts):

return SwaggerModule.createDocument(app, config, {
  // `PostsController` + `create` → `posts.create` (default: `PostsController_create`).
  operationIdFactory: (controllerKey, methodKey) =>
    `${controllerKey.replace(/Controller$/, '').toLowerCase()}.${methodKey}`,
})

With SwaggerModule.setup('docs', …) Nest serves the spec at /docs-json. Point eberly straight at it: swagger: { url: 'http://localhost:3000/docs-json' }. Any http(s) URL works, with or without .json (springdoc’s /v3/api-docs too).

oRPC

Its OpenAPI handler expects arrays of files as files[0], files[1], so set:

files: { encoding: 'bracket-index' },