Reuse specification components with the Component Library in Postman

With the Postman Component Library, you can manage reusable components for your team’s OpenAPI specifications in Spec Hub. Maintain and standardize commonly used components in a central location, without having to redefine them in each specification. Reusable components can include schemas, responses, parameters, and more. Publish a new version when you’re ready to share changes with your team, maintaining support for earlier versions. Anyone on your team can reuse published components and choose the version they’d like to reference in their specifications.

Create a component file

Create a component file in your team’s component library. Name the file and specify the OpenAPI specification format the components will be used in. In the file, define components that your teammates can reuse in their specifications.

1. Click Specs in the sidebar, and open a specification.

2. Click Components in the lower right of the specification.

3. Click Open Component Library.

   

4. Click Add.

5. Enter a name for the component file and select the OpenAPI specification format it’ll be used in. You can’t change the name or OpenAPI specification version of a component file later.

6. Click Create.

   

Postman adds a new component file to your team’s component library in the OpenAPI specification format you chose. Add your own components to the file so your team can reuse them in their specifications.

Edit a component file

Add reusable components to new and existing component files. Define reusable components you’d like to standardize in your team’s specifications, making the component file the single source of truth. You can edit only the draft version of a component file.

1. Click Specs in the sidebar, and open a specification.
2. Click Components in the lower right of the specification.
3. Click Open Component Library.
4. Click a component file in the left sidebar.
5. Make sure the version is set to Draft in the version dropdown list.
6. Add or update reusable components in the file.
7. Click Save.

In the upper right of the editor, you can beautify, wrap, copy, and search content in the component file.

As you edit your component file, Postman displays a live preview of your API’s documentation and identifies syntax errors.

Your teammates can’t reuse components in a draft component file. Publish a version of a component file to allow your teammates to reference its components in their specifications.

View live documentation

Postman displays a live preview of your API’s documentation as you edit your component file. To show the documentation preview, click Live preview in the right sidebar. Click Close to hide the documentation preview.

Validate a component file

Postman identifies syntax errors as you edit your component file. Syntax errors can include missing fields, malformed field names, wrong data types, wrong nesting, or other issues.

Version and publish a component file

Publish a version of a component file to share the latest changes to your reusable components with your team. Versioning component files is useful for publishing a new version of your reusable components, while still supporting earlier versions. You can’t edit versions once they’re published.

1. Click Specs in the sidebar, and open a specification.

2. Click Components in the lower right of the specification.

3. Click Open Component Library.

4. Click a component in the left sidebar that you’d like to version and publish.

5. Click Version & Publish in the upper right corner.

   

6. Enter a version number. The version number must be unique to the component file. The version number can only contain alphanumeric characters, periods, underscores, dashes, plus signs, and no spaces.

7. Click Create Version & Publish.

Once the component is published, your teammates can reference the file’s components in their specifications.

To publish a new version of your component, select Draft in the version dropdown list. Edit the component file and then publish a new version.

Reference a component in a specification

Reference reusable components in your OpenAPI specifications using the URL to the component and its version. A component file must have a published version before you can reference its components in your specification.

1. Click Specs in the sidebar, and open a specification.
2. Click Components in the lower right of a specification
3. Click Open Component Library
4. Search for a component file and select it in the left sidebar.
5. Choose a published version of the component file using the version dropdown list.
6. In the left sidebar, click Copy component link next to a component. This copies the URL to the version of the component you select in the dropdown list.
7. Add the URL to a reference ($ref) in your specification.

As you edit your specification, Postman displays autocomplete suggestions for published components in your team’s component library. Enter a component name as the value of a reference ($ref) and select it from the suggestions list. The URL to the latest version is added as the value.

Postman identifies governance issues for components referenced in your specification. Governance issues are violations of the Postman API Governance rules configured for your team. Learn more about viewing rule violations in your specification.

The Postman CLI also supports running governance rule checks against components referenced in your specification. To learn more, see the postman spec lint command.

Sync components between collections and specifications

Consider the following behavior when syncing changes to reusable components between collections and OpenAPI specifications.

• When you generate a collection from a specification, Postman uses referenced components from your team’s component library to populate relevant parts of the collection.
• When you sync changes from the collection back to the specification, Postman preserves the original reference URL if the values are unchanged. If you change values in the collection that originated from a referenced component, syncing those updates causes Postman to replace the reference URL with the updated inline values.