This article continues the tutorial from the “Invoking API Extractor” page. It’s recommended to start there.
Generating JSON files
API Extractor writes your extracted API signature and doc comments into an intermediary JSON file called
the “doc model” file. To enable this output, you simply need to set
docModel.enabled to true in
your api-extractor.json config file.
The doc model file is written to
"<projectFolder>/temp/<unscopedPackageName>.api.json" by default,
but you can customize this using the
Using api-documenter to generate Markdown
API Extractor includes a companion tool called api-documenter that you can use to generate a basic API reference
website. The Markdown output is fairly basic, since the
MarkdownDocumenter.ts source file was designed to be concise
and understandable, while still functionally complete. That way it can serve as a starting point for people who want
to implement their own adapter to process API Extractor’s doc model using a custom pipeline (discussed later).
Even so, Markdown output can be a realistic solution if your needs are not too fancy, and it is very easy to use.
As input, api-documenter accepts a folder containing doc model files, one for each package that you want to incorporate. This allows a collection of related projects to be built separately (perhaps in separate Git repos using different toolchains). The documentation pipeline collects these JSON files, and then uses them to generate a single website, complete with cross-package hyperlinks and an integrated navigation tree.
Here’s a typical usage scenario:
(Separately) Invoke API Extractor for each project that you want to document. This will produce one or more .api.json files.
Copy your .api.json files into an input folder, for example:
- ~/my-docs/input/ (.api.json inputs go here)
- ~/my-docs/markdown/ (.md output files will go here)
Install the api-documenter tool in your global environment, using a shell command like this:
$ npm install -g @microsoft/api-documenter
PATHenvironment variable is set up correctly, now you should now be able to invoke
api-documenterfrom your shell.
Run the api-documenter tool like this:
$ cd ~/my-docs/ $ api-documenter markdown
You can customize these folders using parameters such as
--output-folder. See the command line reference for details.
What do we do with these generated Markdown files? There are various options:
GitHub: If you’re using GitHub, you can simply commit them to your master branch in a “docs” folder, and they will be rendered using GitHub’s markdown previewer. Here’s an example of how it looks: node-core-library.md
GitHub Pages: If you use GitHub pages to host a web site for your project, your repo will probably have a “gh-pages” branch. You can add the Markdown files there, as seen here:
Example website: https://rushstack.io/pages/api/
Docusaurus: These Markdown files can also be rendered using Docusaurus, which produces a React-based web site using Markdown inputs.
Example branch: https://github.com/faastjs/faast.js/tree/master/docs/api
Example website: https://faastjs.org/docs/api/faastjs
Using api-documenter with DocFX
If Markdown output is the “go-kart” of documentation generation, then
DocFX is the “space shuttle”. It’s a fairly complex but professional
system with nearly every feature imaginable, since it was created to power
docs.microsoft.com. As far as API Extractor’s involvement, the workflow is the same
as above, except that the shell command is
api-documenter yaml instead of
Setting up DocFX can be a little challenging (unless you work at Microsoft, in which case it’s super easy! :-) ).
The sites that DocFX produces are very full-featured. Here’s a couple API references that were generated using api-documenter with DocFX:
These are nice options. But suppose you have custom needs, and you’re not afraid to write some code to get what you want…