Transforms API Extractor .api.json files into .page.json files
npm install @fluentui/api-docsProcesses package-name.api.json files generated by API Extractor into ComponentName.page.json files used to populate API reference tables, mainly in the Fluent UI website's Controls section.
1. In each API item which should be included on the website (see Limitations below for supported item types), include a {@docCategory PageName} annotation in its top-level doc comment. If the item is related to a specific component, PageName should be the name of the component. Otherwise, you can use either the name of the item or a general category that it falls under.
``ts`
/**
* Comment about the props
* {@docCategory Foo}
*/
interface FooProps {}
2. Add a config and build step to run API Extractor on your package. (Fluent UI has a shared config extended by each package's config.)
3. Somewhere in your repo (probably in the package that displays the documentation), add a build step to invoke the generatePageJsonFiles API. For the config object, see IPageJsonOptions in this file for docs and this file for an example.
`js`
const { generatePageJsonFiles } = require('@fluentui/api-docs');
const config = {}; // your config here
generatePageJsonFiles(config);
4. To render the info from *.page.json files, you can either use ApiReferencesTableSet from @fluentui/react-docsite-components, or use its logic as a template for your own control.
Documenting the following API items/types is supported:
- Interfaces
- Type aliases
- Classes
- Enums
These API items/types are not supported currently (PRs welcome):
- Functions (including function components)
- Constants
If you're using ApiReferencesTableSet for rendering the output, top-level doc comments have full markdown support, but individual prop comments have limited support (currently just inline code blocks) due to performance concerns. (May not apply if you've written your own renderer.)
API Extractor has a particular format required for certain types of doc comments and will fail at build time if this format is not followed. There are also a few suggested best practices.
| Good | Bad | |
|---|---|---|
@param tags must include a dash and not contain type information | | |
Special characters which have meaning in TSDoc (e.g. @ > { }) must be escaped with backslashes or backticks | | |
@deprecated tags should include a deprecation message | | |
Default values should be indicated by @defaultvalue tags (@default and @defaultValue also work) | | |