APIScan

APIScan is a tool run on shipping binaries for products across Microsoft to ensure that all APIs called in designated High-Volume Products (HVPs) are publicly documented. This is a compliance requirement, designed to ensure that Microsoft does not have an undue advantage over third party developers when it comes to using APIs between products. For example, any Office API called by SQL Server must be publicly documented.

For APIScan to work, certain metadata must be set on reference topics. When this metadata is set correctly on a topic corresponding to an API, we get an entry for that API in the APIScan database, which indicates that the API is documented. This topic describes how to set that metadata for content in OPS.

In order to make the reference document available for API Scan, content team needs to apply corresponding metadata to indicate that a document is one or more API, the name of the API, the type of the API, and the assembly name that contains the API. Metadata will be published along with the document. OPS will extract API document with its API metadata in reporting database.

Configuring the docset for API Scan

If you do not have right to do this or need help, enter a request in SiteHelp portal.

Configuring APIScan for managed reference docsets

For managed reference, required APIScan metadata is generate automatically based on information in the documented assemblies. You just have to turn it on, as follows:

  1. To enable API Scan for a docset, set the "API Scan" to "true" in the OPS self-service portal. The default value of the option is currently false, which means it skips API Scan by default.

  2. As a best practice, provide the product family of the docset in OPS self-service portal, this is set to "product_family" metadata.

API Scan - docset

The mref build system will apply the following metadata:

  • topictype = apiref. This is the switch that turns on APIScan for a topic.
  • apitype = assembly.
  • apiname = the name of the API.
  • apilocation = the DLL(s) in which teh API is defined.

Configuring APIScan for non-managed reference

For non-managed reference, such as COM, writers must add APIScan metadata manually, or migrate it from a previous system such as CAPS. The APIScan metadata goes with other metadata in the YAML header, or can be applied globally in docfx.json for values that apply to an entire docset.

API Scan - header

  • product: multi-value, specified as a global metadata in docfx.json, thus all the documents in this DocSet will have same value of "product" metadata.
  • topictype: multi-value, must have "apiref" as one of its values, otherwise this document will be skipped for API Scan.
  • apiname: multi-value, at least one value is specified
  • apitype: multi-value
  • apilocation: multi-value
  1. In the doc.fx file, add global metadata "product" so it applies to all the docSet:

API Scan - metadata