feat: allow swagger operation customization via transformOperation

[sjorobekov]

Summary

This PR introduces transformOperation, a new callback in createOpenApiRegistry that allows for fine-grained customization of generated OpenAPI operations.
Additionally, the README.md has been significantly simplified to make the documentation clearer and more focused.

Details

🛠 transformOperation Callback

Previously, customizing the generated OpenAPI specs for specific routes was limited to what the built-in wrappers provided. The new transformOperation callback gives developers full control to patch the OpenApiOperation object right before it is registered.

How it works:
The callback receives the current operation object and a context object containing the HTTP method, the OpenAPI-formatted path, and the full AppRouteDescription (route).

Example Usage:

const {registerRoutes} = createOpenApiRegistry({
  title: 'My API',
  transformOperation: (operation, {path, route}) => {
    // 1. Patch by specific path
    if (path === '/items') {
      return {
        ...operation,
        security: [{ customApiKey: [] }],
      };
    }
    // 2. Patch by route property (e.g., mark public routes)
    if (route.authPolicy === 'disabled') {
      return {
        ...operation,
        description: `(Public) ${operation.description || ''}`,
      };
    }
    // 3. Apply global changes (e.g., add a default tag)
    return {
      ...operation,
      tags: [...(operation.tags || []), 'Global'],
    };
  },
});

[Copilot]

Pull request overview

Adds a new transformOperation hook to the OpenAPI registry so callers can programmatically patch the generated OpenAPI operation per-route (based on method/path/route description), and updates docs/tests accordingly.

Changes:

• Extend createOpenApiRegistry config with transformOperation(operation, context) to customize operations before registration.
• Refactor operation-building logic in openapi-registry.ts and add test coverage for the new hook.
• Simplify and update README.md with a new “Customizing the OpenAPI operation” section.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
src/types.ts	Adds transformOperation to OpenApiRegistryConfig and introduces OpenApiOperation type.
src/openapi-registry.ts	Wires transformOperation into route registration and refactors operation construction helpers.
src/tests/openapi-registry.test.ts	Adds tests verifying operation patching and transformer context.
src/index.ts	Re-exports OpenApiRegistry type from the public entrypoint.
README.md	Simplifies docs and documents transformOperation usage.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

You can also share your feedback on Copilot code review. Take the survey.