Design and build APIsDesign APIs with specifications

Import an API specification

View as Markdown

You can import an existing OpenAPI, AsyncAPI, protobuf, and GraphQL specifications in Spec Hub. Import a single or multi-file OpenAPI specification as a collection or a specification and collection. Import an AsyncAPI or GraphQL single file or protobuf multi-file specification in Spec Hub only.

If you try to import an unsupported format using Import in the sidebar, Postman only gives you the option to import into the API Builder.

  1. Click Import in the sidebar.

  2. Choose one of the following options to import a specification file:

    • Click files, then select a specification file. Use this to import single file OpenAPI, AsyncAPI, protobuf, or GraphQL specifications.

    • Click folder, then select a folder with a multi-file OpenAPI or protobuf specification.

      You can also import more than one multi-file OpenAPI or protobuf specification at the same time.

    • Enter a link to a specification file.

    • Paste raw text.

    • Import from a remote GitHub, Bitbucket, GitLab, or Azure DevOps repository. Click Other Sources, and then select GitHub, Bitbucket, GitLab, or Azure. Follow the instructions to sign in to your repository. Then select the repository and other relevant details and select the branch you want to import from.

  3. If you’re importing a single or multi-file OpenAPI specification, choose how you’d like to import it into Postman, then click Import. Note that AsyncAPI and protobuf specifications are automatically imported as a new specification in Spec Hub.

    • Postman Collection - Generates a collection with folders, requests, and response examples based on the specification. A new specification isn’t created in Spec Hub.

    • Specification with a Postman Collection - Generates a collection from the provided OpenAPI or GraphQL specification and creates a new specification in Spec Hub. For OpenAPI 3.0 specifications, if you update it, you can then update the collection with the latest changes to the specification. Learn more about keeping OpenAPI collections in sync with a specification.

      If you’re importing more than one multi-file OpenAPI specification, you can also choose how you’d like to import them into Postman. By default, Postman generates a collection based on each specification. You can select the Import these as specs checkbox to create a new specification in Spec Hub for each multi-file specification.

    You can also click Setting icon View Import Settings for more configuration options. These options will vary depending on your specification.

  4. In the Importing message that displays in the Postman footer, click Open in Postman icon Go to Specification next to a specification or Open in Postman icon Go to Collection next to a collection.

Your Postman plan gives you a limited number of specifications in your team’s internal workspaces. Learn more about resource usage in Postman.

Postman stores your authorized accounts so you can use them to connect to other repositories and services. Learn more about managing connected accounts for remote repositories.