@azure-tools/typespec-apiview

TypeSpec APIView Emitter

This package provides the TypeSpec emitter to produce APIView token file output from TypeSpec source.

Install

Add @azure-tools/typespec-apiview to your package.json and run npm install.

Emit APIView spec

1. Via the command line

tsp compile {path to typespec project} --emit=@azure-tools/typespec-apiview

1. Via the config

Add the following to the typespec-project.yaml file.

emitters:
  @azure-tools/typespec-apiview: true

For configuration see options

Create API View

1. Log in to the API View site (apiview.dev)[https://apiview.dev].
2. Click the blue "Create Review" button in the bottom-right corner of the screen.
3. In the first block, load the token file generated by the typespec-apiview emitter.

Revise API View

1. Log in to the API View site (apiview.dev)[https://apiview.dev].
2. Navigate to your review.
3. Click the "Revisions" tab in the top left.
4. Click the blue "Add Revision" button in the bottom-right corner of the screen.
5. In the first block, load the token file generated by the typespec-apiview emitter.

Use APIView-specific decorators:

Currently there are no APIView-specific decorators...

Emitter options:

Emitter options can be configured via the tspconfig.yaml configuration:

emitters:
  '@azure-tools/typespec-apiview':
    <optionName>: <value>


# For example
emitters:
  '@azure-tools/typespec-apiview':
    output-file: my-custom-apiview.json

or via the command line with

--option "@azure-tools/typespec-apiview.<optionName>=<value>"

# For example
--option "@azure-tools/typespec-apiview.output-file=my-custom-apiview.json"

emitter-output-dir

Configure the name of the output directory. Default is tsc-output/@azure-tools/typespec-apiview.

include-global-namespace

Normally, APIView will filter all namespaces and only output those in the service namespace and any subnamespaces. This is to filter out types that come from the TypeSpec compiler and supporting libraries. This setting, if true, tells APIView to output the contents of the global (empty) namespace, which would normally be excluded.

service

Filter output to a single service definition. If omitted, all service defintions will be output as separate APIView token files.

output-file

Configure the name of the output JSON token file relative to the output-dir. For multi-service specs, this option cannot be supplied unless the service option is also set. If outputting all services in a multi-service spec, the output filename will be the service root namespace with the -apiview.json suffix. Otherwise, the default is apiview.json.

version

For multi-versioned TypeSpec, this parameter is used to control which version to emit. This is not required for single-version specs. For multi-versioned specs, the unprojected TypeSpec will be rendered if this is not supplied. For multi-service specs, this option cannot be supplied unless the service option is also set.

See also

• TypeSpec Getting Started
• TypeSpec Tutorial
• TypeSpec for the OpenAPI Developer