Postman Now Generates Docs from OpenAPI 3.0 Definitions

During various stages of an API lifecycle, API producers need to communicate their API’s functionality to consumers who may have various degrees of API awareness. Consumers—internal, partner, or public—aren’t always engineers who can understand an API specification; they may perform different functions and be from different teams, such as QA, DevOps, go-to-market, product, etc. This means there’s a growing need for an API specification to be in a more consumable form so that users can effortlessly understand an API’s functionality and quickly get started with your APIs.

To resolve this need, especially because the Postman API Platform is built for collaboration, Postman now automatically generates reference documentation from your OpenAPI 3.0 definitions.

Related: What is API documentation?

API schema documentation in the API Builder

The API Builder will now also include generated reference documentation along with the OpenAPI 3.0 definition, enabling your collaborators and consumers to quickly and comprehensively understand your API’s functionality in every stage of the API lifecycle. While in design, you can use the generated documentation to get quick feedback. During development and testing, make sure consumers and QA engineers can get started quickly in parallel. Once deployed, you can share your API along with its reference documentation through workspaces and the API Network.

Comprehensively communicate API functionality

The generated documentation will contain the complete information necessary to consume your API:

API Overview

The API Overview section will give an overview of the API derived from your OpenAPI definition:

Operations

You can browse all operations defined on your API endpoints to understand the functionality.

Parameters

Params, headers, and other key-value pairs for every operation will now convey if they are required or optional, type/format, and other constraints.

Request body

Request body will convey properties with their schema information. Individual objects can be expanded to view constituent properties.

Responses

For every operation, you can view all the responses and their schema.

The auto-generated API documentation will make it easier for a consumer to quickly construct a request according to their use case. They will also be less prone to errors. Response body schema and examples will help consumers interpret responses and use your APIs quicker.

Check it out

Check out Postman API’s documentation in Postman’s public workspace to understand how your API reference documentation can be showcased. Though limited to OpenAPI 3.0 right now, we would love to expand this solution to other specification formats using your feedback or comments. Try it out and tell us what you think in a comment below. You can also give product feedback through our Community forum and GitHub repository.

Try Postman now