Rush StackShopBlogEvents
Skip to main content

Generating API docs

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 docModel.apiJsonFilePath setting.

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:

  1. (Separately) Invoke API Extractor for each project that you want to document. This will produce one or more .api.json files.

  2. 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)
  3. Install the api-documenter tool in your global environment, using a shell command like this:

    ```shell
    $ npm install -g @microsoft/api-documenter
    ```

    Assuming your `PATH` environment variable is set up correctly, now you should now be able to invoke
    `api-documenter` from your shell.
  4. Run the api-documenter tool like this:

    $ cd ~/my-docs/
    $ api-documenter markdown

    You can customize these folders using parameters such as --input-folder and --output-folder. See the command line reference for details.

What do we do with these generated Markdown files? There are various options:

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 api-documenter markdown. 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...