fix(openapi3): don't emit auth scheme models under components.schemas

[dschmidt]

Issue

A custom auth scheme model declared inside the service namespace is emitted into both components.securitySchemes (correct) and components.schemas (spurious):

@useAuth(customBearer)
@service
namespace MyService;

model customBearer {
  type: AuthType.http;
  scheme: "bearer";
}

Emitted output today:

components:
  schemas:
    customBearer:                # <-- spurious
      type: object
      required: [type, scheme]
      properties: { ... }
  securitySchemes:
    customBearer:                # <-- correct
      type: http
      scheme: bearer

The spurious components.schemas.<name> entry comes from processUnreferencedSchemas, which walks every model in the service namespace and emits any model that is "unreachable" (i.e. not referenced from any payload). Custom auth scheme models always match that criterion but are already covered by components.securitySchemes.

Visible symptom (how I found this): @extension(...) decorators applied to the auth model propagate to both emit locations. Extensions valid under components.securitySchemes.<name> (for example bearerFormat: plain on a bearer auth scheme) are unknown under components.schemas.<name>, and downstream tools — openapi-generator-cli's spec validator in my case — reject the document:

- Error count: 1, Warning count: 4
Errors:
  -attribute components.schemas.customBearer.bearerFormat is unexpected

The bug only triggers when the auth model is declared inside the service namespace. Declared at global scope it doesn't reproduce, because processUnreferencedSchemas only walks the service namespace.

Fix

Filter auth scheme model types out of processUnreferencedSchemas. serviceAuth.schemes already carries each scheme's originating model (HttpAuth.model) by the time emitSchemas runs.

const authSchemeModels = new Set<Type>(serviceAuth.schemes.map((s) => s.model));
const addSchema = (type: Type) => {
  if (isOrExtendsHttpFile(program, type)) return;
  if (authSchemeModels.has(type)) return;  // skip auth scheme models
  if (visibilityUsage.isUnreachable(type) && !paramModels.has(type) && !shouldInline(program, type)) {
    callSchemaEmitter(type, Visibility.All);
  }
};

Auth models continue to be emitted via the separate securitySchemes path in initializeEmitter.

Test

Added a test case in packages/openapi3/test/security.test.ts that asserts res.components.schemas?.customBearer is undefined while res.components.securitySchemes.customBearer is set correctly. All 60 existing security tests still pass.

Backward compatibility

I think this should be safe: depending on auth scheme models to appear under components.schemas would be a misuse — they're not payload schemas. The change only affects the emit location, the model still parses and resolves identically inside @useAuth(...).

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/@typespec/openapi3@10677

commit: 2c2c513

[github-actions]

All changed packages have been documented.

• ✅ @typespec/openapi3

Show changes

@typespec/openapi3 - fix ✏️

Fix custom auth scheme models leaking into components.schemas when declared inside the service namespace. They are now emitted only under components.securitySchemes as expected.