Replace @microsoft/api-extractor with TypeDoc

[timotheeguerin]

Motivation

@microsoft/api-extractor is aging, lightly maintained, and — most importantly — does not support modern ESM export maps (multiple entry points). This PR replaces its two uses in the core TypeSpec packages + tspd with TypeDoc.

Scope: core packages + tspd only. The Azure emitter / APIView integration in http-client-csharp / http-client-java is out of scope and keeps its self-contained api-extractor setup.

What changed

1. tspd typekit reference docs (@microsoft/api-extractor-model → TypeDoc)

• New packages/tspd/src/ref-doc/typekit-model.ts builds the typekit model from TypeDoc.
• Removed api-extractor.ts + tsdoc.tsx and the 4 @microsoft/{api-extractor,api-extractor-model,tsdoc,tsdoc-config} dependencies.
• Regenerated typekits.mdx for the standard library and http (output is equivalent; only intended diffs).

2. Public-API documentation enforcement (ae-undocumented → TypeDoc)

• New eng/tsp-core/scripts/check-api-docs.ts: a TypeDoc-based checker that validates every stable public entry point (unlike api-extractor's single entry point), supporting ESM export maps.
• Replaced the api-extractor package script with check-api-docs in compiler, http, openapi, openapi3, json-schema, xml, asset-emitter.
• Wired check-api-docs into build for the three packages that enforced docs before (json-schema, openapi, xml) — all pass with parity (0 findings).

3. Removal

• Deleted api-extractor.base.json and the 8 per-package api-extractor.json configs.
• Removed the @microsoft/api-extractor* catalog entries and root devDependency.

Notes

• compiler / http / openapi3 / asset-emitter have check-api-docs available but not wired into build yet — they carry pre-existing doc debt. Enabling enforcement there is a future docs effort.
• A public-API breaking-change detection replacement (snapshot-based CI check) is a possible follow-up and is not included here.

Validation

• check-api-docs passes for json-schema / openapi / xml (parity with the old ae-undocumented).
• tspd builds and lints clean; regenerated docs contain only intended diffs.

[microsoft-github-policy-service]

@FionaBronwen @swatkatz @steverice — this PR modifies files in the emitter:graphql area, which your team owns. Please take a look. (You can't be added as a formal reviewer because you're not a repository collaborator, so this is a heads-up instead.)

[pkg-pr-new]

Open in StackBlitz

@typespec/asset-emitter

npm i https://pkg.pr.new/@typespec/asset-emitter@11384

@typespec/compiler

npm i https://pkg.pr.new/@typespec/compiler@11384

@typespec/graphql

npm i https://pkg.pr.new/@typespec/graphql@11384

@typespec/http

npm i https://pkg.pr.new/@typespec/http@11384

@typespec/json-schema

npm i https://pkg.pr.new/@typespec/json-schema@11384

@typespec/openapi

npm i https://pkg.pr.new/@typespec/openapi@11384

@typespec/openapi3

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

@typespec/tspd

npm i https://pkg.pr.new/@typespec/tspd@11384

@typespec/xml

npm i https://pkg.pr.new/@typespec/xml@11384

commit: 1159259

[github-actions]

All changed packages have been documented.

• ✅ @typespec/asset-emitter
• ✅ @typespec/compiler
• ✅ @typespec/graphql
• ✅ @typespec/http
• ✅ @typespec/json-schema
• ✅ @typespec/openapi
• ✅ @typespec/openapi3
• ✅ @typespec/tspd
• ✅ @typespec/xml

Show changes

@typespec/compiler - internal ✏️

Replace the @microsoft/api-extractor public API documentation enforcement with a TypeDoc-based check-api-docs check that supports modern ESM export maps and validates every stable public entry point.

@typespec/http - internal ✏️

Replace the @microsoft/api-extractor public API documentation enforcement with a TypeDoc-based check-api-docs check that supports modern ESM export maps and validates every stable public entry point.

@typespec/openapi - internal ✏️

Replace the @microsoft/api-extractor public API documentation enforcement with a TypeDoc-based check-api-docs check that supports modern ESM export maps and validates every stable public entry point.

@typespec/openapi3 - internal ✏️

Replace the @microsoft/api-extractor public API documentation enforcement with a TypeDoc-based check-api-docs check that supports modern ESM export maps and validates every stable public entry point.

@typespec/json-schema - internal ✏️

Replace the @microsoft/api-extractor public API documentation enforcement with a TypeDoc-based check-api-docs check that supports modern ESM export maps and validates every stable public entry point.

@typespec/xml - internal ✏️

Replace the @microsoft/api-extractor public API documentation enforcement with a TypeDoc-based check-api-docs check that supports modern ESM export maps and validates every stable public entry point.

@typespec/asset-emitter - internal ✏️

Replace the @microsoft/api-extractor public API documentation enforcement with a TypeDoc-based check-api-docs check that supports modern ESM export maps and validates every stable public entry point.

@typespec/graphql - internal ✏️

Replace the @microsoft/api-extractor public API documentation enforcement with a TypeDoc-based check-api-docs check that supports modern ESM export maps and validates every stable public entry point.

@typespec/tspd - internal ✏️

Migrate typekit reference documentation generation from @microsoft/api-extractor to TypeDoc, removing the @microsoft/api-extractor, @microsoft/api-extractor-model, @microsoft/tsdoc and @microsoft/tsdoc-config dependencies.

[azure-sdk-automation]

You can try these changes here

🛝 Playground	🌐 Website	🛝 VSCode Extension