@microsoft/api-extractor-model

Use this library to read and write *.api.json files as defined by the API Extractor tool. These files are used to generate a documentation website for your TypeScript package. The files store the API signatures and doc comments that were extracted from your package.

API documentation for this package: https://rushstack.io/pages/api/api-extractor-model/

Example Usage

The following code sample shows how to load example.api.json, which would be generated by API Extractor when it analyzes a hypothetical NPM package called example:

import { ApiModel, ApiPackage } from '@microsoft/api-extractor-model';

const apiModel: ApiModel = new ApiModel();
const apiPackage: ApiPackage = apiModel.loadPackage('example.api.json');

for (const member of apiPackage.members) {
  console.log(member.displayName);
}

The ApiModel is acts as a container for various packages that are loaded and operated on as a group. For example, a documentation tool may need to resolve @link references across different packages. In this case we would load the various packages into the ApiModel, and then use the ApiModel.resolveDeclarationReference() to resolve the @link targets.

The data structure forms a tree of various classes that start with the Api prefix. The nesting hierarchy might look like this:

- ApiModel
  - ApiPackage
    - ApiEntryPoint
      - ApiClass
        - ApiMethod
        - ApiProperty
      - ApiEnum
        - ApiEnumMember
      - ApiInterface
        - ApiMethodSignature
        - ApiPropertySignature
      - ApiNamespace
        - (ApiClass, ApiEnum, ApiInterace, ...)

You can use the ApiItem.members property to traverse this tree.

Note that the non-abstract classes (e.g. ApiClass, ApiEnum, ApiInterface, etc.) use TypeScript "mixin" functions (e.g. ApiDeclaredItem, ApiItemContainerMixin, etc.) to add various features that cannot be represented as a normal inheritance chain (since TypeScript does not allow a child class to extend more than one base class). The "mixin" is a TypeScript merged declaration with three components: the function that generates a subclass, an interface that describes the members of the subclass, and a namespace containing static members of the class.

For a complete project that uses these APIs to generate an API reference web site, see the @microsoft/api-documenter source code.

Links

• CHANGELOG.md - Find out what's new in the latest version
• API Reference

API Extractor is part of the Rush Stack family of projects.

Change Log - @microsoft/api-extractor-model

This log was last generated on Fri, 05 Feb 2021 16:10:42 GMT and should not be manually modified.

7.12.2

Fri, 05 Feb 2021 16:10:42 GMT

Version update only

7.12.1

Thu, 10 Dec 2020 23:25:49 GMT

Patches

• Enable support for @decorator

7.12.0

Wed, 18 Nov 2020 08:19:54 GMT

Minor changes

• Introduce an ApiOptionalMixin base class for representing optional properties and methods

7.11.0

Wed, 18 Nov 2020 06:21:57 GMT

Minor changes

• Update .api.json file format to store a new field "isOptional" for documenting optional properties

7.10.10

Wed, 11 Nov 2020 01:08:59 GMT

Version update only

7.10.9

Tue, 10 Nov 2020 23:13:12 GMT

Version update only

7.10.8

Fri, 30 Oct 2020 06:38:39 GMT

Version update only

7.10.7

Fri, 30 Oct 2020 00:10:14 GMT

Version update only

7.10.6

Thu, 29 Oct 2020 06:14:19 GMT

Patches

• Fix .d.ts error when the library is imported by a project using TypeScript 4.0

7.10.5

Wed, 28 Oct 2020 01:18:03 GMT

Version update only

7.10.4

Tue, 27 Oct 2020 15:10:14 GMT

Version update only

7.10.3

Tue, 06 Oct 2020 00:24:06 GMT

Version update only

7.10.2

Mon, 05 Oct 2020 22:36:57 GMT

Version update only

7.10.1

Wed, 30 Sep 2020 18:39:17 GMT

Patches

• Update to build with @rushstack/heft-node-rig

7.10.0

Wed, 30 Sep 2020 06:53:53 GMT

Minor changes

• Upgrade compiler; the API now requires TypeScript 3.9 or newer

Patches

• Update README.md

7.9.7

Tue, 22 Sep 2020 05:45:57 GMT

Version update only

7.9.6

Tue, 22 Sep 2020 01:45:31 GMT

Version update only

7.9.5

Tue, 22 Sep 2020 00:08:53 GMT

Version update only

7.9.4

Sat, 19 Sep 2020 04:37:27 GMT

Version update only

7.9.3

Sat, 19 Sep 2020 03:33:07 GMT

Version update only

7.9.2

Fri, 18 Sep 2020 22:57:24 GMT

Version update only

7.9.1

Fri, 18 Sep 2020 21:49:54 GMT

Version update only

7.9.0

Sun, 13 Sep 2020 01:53:20 GMT

Minor changes

• Add support for system selectors in declaration references

7.8.22

Fri, 11 Sep 2020 02:13:35 GMT

Version update only

7.8.21

Mon, 07 Sep 2020 07:37:37 GMT

Version update only

7.8.20

Sat, 05 Sep 2020 18:56:34 GMT

Patches

• Fix "Converting circular structure to JSON" error (GitHub #2152)

7.8.19

Thu, 27 Aug 2020 11:27:06 GMT

Version update only

7.8.18

Mon, 24 Aug 2020 07:35:20 GMT

Version update only

7.8.17

Sat, 22 Aug 2020 05:55:43 GMT

Version update only

7.8.16

Tue, 18 Aug 2020 23:59:42 GMT

Version update only

7.8.15

Mon, 17 Aug 2020 04:53:23 GMT

Version update only

7.8.14

Wed, 12 Aug 2020 00:10:05 GMT

Patches

• Updated project to build with Heft

7.8.13

Wed, 05 Aug 2020 18:27:33 GMT

Version update only

7.8.12

Fri, 03 Jul 2020 15:09:04 GMT

Version update only

7.8.11

Thu, 25 Jun 2020 06:43:35 GMT

Version update only

7.8.10

Wed, 24 Jun 2020 09:50:48 GMT

Version update only

7.8.9

Wed, 24 Jun 2020 09:04:28 GMT

Version update only

7.8.8

Wed, 10 Jun 2020 20:48:30 GMT

Version update only

7.8.7

Sat, 30 May 2020 02:59:54 GMT

Version update only

7.8.6

Thu, 28 May 2020 05:59:02 GMT

Version update only

7.8.5

Wed, 27 May 2020 05:15:11 GMT

Version update only

7.8.4

Tue, 26 May 2020 23:00:25 GMT

Version update only

7.8.3

Fri, 22 May 2020 15:08:43 GMT

Version update only

7.8.2

Thu, 21 May 2020 23:09:44 GMT

Version update only

7.8.1

Thu, 21 May 2020 15:42:00 GMT

Version update only

7.8.0

Wed, 06 May 2020 08:23:45 GMT

Minor changes

• Enable canonicalReference to ApiItem lookup

7.7.11

Wed, 08 Apr 2020 04:07:33 GMT

Version update only

7.7.10

Sat, 28 Mar 2020 00:37:16 GMT

Patches

• Upgrade to TSdoc 0.12.19

7.7.9

Wed, 18 Mar 2020 15:07:47 GMT

Patches

• Upgrade cyclic dependencies

7.7.8

Tue, 17 Mar 2020 23:55:58 GMT

Patches

• Replace dependencies whose NPM scope was renamed from @microsoft to @rushstack

7.7.7

Tue, 28 Jan 2020 02:23:44 GMT

Version update only

7.7.6

Thu, 23 Jan 2020 01:07:56 GMT

Version update only

7.7.5

Tue, 21 Jan 2020 21:56:14 GMT

Version update only

7.7.4

Sun, 19 Jan 2020 02:26:52 GMT

Patches

• Upgrade Node typings to Node 10

7.7.3

Fri, 17 Jan 2020 01:08:23 GMT

Version update only

7.7.2

Thu, 09 Jan 2020 06:44:13 GMT

Version update only

7.7.1

Wed, 08 Jan 2020 00:11:31 GMT

Version update only

7.7.0

Tue, 03 Dec 2019 03:17:43 GMT

Minor changes

• Improve declaration reference syntax to allow linking to overloaded functions/methods

7.6.0

Sun, 24 Nov 2019 00:54:04 GMT

Minor changes

• Added support for @throws

7.5.6

Fri, 15 Nov 2019 04:50:50 GMT

Version update only

7.5.5

Mon, 11 Nov 2019 16:07:56 GMT

Version update only

7.5.4

Tue, 05 Nov 2019 06:49:28 GMT

Patches

• Fix an issue where API reports sometimes were ordered differently depending on the version of NodeJS (GitHub #1552)

7.5.3

Tue, 05 Nov 2019 01:08:39 GMT

Patches

• Clarified an error message

7.5.2

Tue, 22 Oct 2019 06:24:44 GMT

Patches

• Refactor some code as part of migration from TSLint to ESLint

7.5.1

Sun, 29 Sep 2019 23:56:29 GMT

Patches

• Update repository URL

7.5.0

Wed, 25 Sep 2019 15:15:31 GMT

Minor changes

• Add ApiItem.getMergedSiblings() API

7.4.2

Mon, 23 Sep 2019 15:14:55 GMT

Patches

• Remove unnecessary dependency on @types/node

7.4.1

Tue, 10 Sep 2019 22:32:23 GMT

Patches

• Update documentation

7.4.0

Tue, 10 Sep 2019 20:38:33 GMT

Minor changes

• Add 'canonicalReference' to ExcerptToken

7.3.4

Wed, 04 Sep 2019 18:28:06 GMT

Version update only

7.3.3

Wed, 04 Sep 2019 15:15:37 GMT

Patches

• Update TSDoc dependency to 0.12.14

7.3.2

Thu, 08 Aug 2019 15:14:17 GMT

Version update only

7.3.1

Thu, 08 Aug 2019 00:49:05 GMT

Patches

• (Experimental) Add ApiExtractor.canonicalReference which is a beta implementation of the revised TSDoc declaration reference notation

7.3.0

Mon, 22 Jul 2019 19:13:10 GMT

Minor changes

• Rename ApiItem.canonicalReference to .containerKey; rename ApiItemContainerMixin.tryGetMember() to .tryGetMemberByKey(); rename Api___.getCanonicalReference() to .getContainerKey()

7.2.0

Tue, 11 Jun 2019 00:48:06 GMT

Minor changes

• Add API support for type parameters and type alias types

Patches

• Improve the .api.json deserializer to validate the schema version and support backwards compatibility

7.1.3

Wed, 05 Jun 2019 19:12:34 GMT

Patches

• Fix an issue where TSDoc index selectors (ApiParameterListMixin.overloadIndex) started from 0, whereas TSDoc requires a nonzero number

7.1.2

Tue, 04 Jun 2019 05:51:53 GMT

Patches

• Fix an issue where ApiConstructor inherited from ApiStaticMixin, but TypeScript constructors cannot be static

7.1.1

Mon, 27 May 2019 04:13:44 GMT

Patches

• Make the strings returned by ApiItem.displayName less verbose
• Improve formatting of the strings returned by ApiItem.getScopedNameWithinPackage()

7.1.0

Tue, 16 Apr 2019 11:01:37 GMT

Minor changes

• Initial stable release of API Extractor 7

7.0.28

Wed, 20 Mar 2019 19:14:49 GMT

Version update only

7.0.27

Mon, 18 Mar 2019 04:28:43 GMT

Patches

• Add helper functions for ReleaseTag
• Export IApiItemConstructor to eliminate the ae-forgotten-export warning

7.0.26

Wed, 13 Mar 2019 19:13:14 GMT

Patches

• Refactor code to move the IndentedWriter API from api-extractor-model to api-documenter

7.0.25

Wed, 13 Mar 2019 01:14:05 GMT

Patches

• Upgrade TSDoc

7.0.24

Mon, 11 Mar 2019 16:13:36 GMT

Patches

• Initial setup of new package @microsoft/api-extractor-model