Overview

An API spec template gives an organization a common starting point for new OpenAPI specs. A template spec holds the starting content, and a template policy decides which repositories can use it.

Creating or changing templates and template policies requires the Enterprise plan, and templates are available only in organization repositories. Only organization owners can see the organization’s Governance tab.

Create a Template Spec

1. Open your organization and select the Governance tab
2. Select API Template and then Template Spec
3. Click the plus icon next to API Spec Templates (tooltip add spec template)
4. Use the pencil next to Basic Info to set the name and description
5. Use the pencil next to Spec Content to open the Edit Template dialog, enter the spec as JSON and click Save

Deleting a template also deletes the policies that use it.

Apply a Template With a Policy

A template appears in a repository only when a template policy covers that repository.

1. Select API Template and then Template Policy
2. Click the plus icon next to Template Policies (tooltip Create a new policy)
3. Choose the template under Template:
4. Turn on Apply to all repositories, or pick repositories under Repositories:
5. Click Save

A template can be used by only one policy in an organization.

The Overview tab shows the Template Usage Report, which lists the templates applied to each repository.

Create a Spec From a Template

1. In the repository, click the plus icon at the top of the file tree
2. On the OpenApi Spec tab, keep create openAPI spec selected
3. Choose a template under API Spec Template
4. Enter a path name and click Create

A template is used once, when the file is created. The new spec is an ordinary file in your repository, and nothing checks it against the template afterwards. To check specs continuously, use governance rules.