Documentation
Capturing Traffic
Postman

Use Postman Collections to keep your OpenAPI up-to-date

Postman Collections (opens in a new tab) make it easy for developers to store and execute API requests during development and testing. Collections store a lot of information about your API, but unfortunately are not directly compatible with the OpenAPI Standard. That makes it difficult to use other tooling for documentation, governance, and code generation. Optic makes it easy to adopt OpenAPI. Our CLI (opens in a new tab) is like Git, but for tracking API changes. It keeps your OpenAPI spec up-to-date by looking at real traffic, and patching the specification whenever it detects an API change.

alt

Postman Collection to OpenAPI with Optic

Optic has official support for Postman Collections as a capture source. This means the traffic in your Collection can be used to generate OpenAPI and update that spec as you make changes.

optic verify openapi.yml --postman collection.json

Step 1: Save Examples in your Collection

Optic learns from the examples in your Postman Collection. You can save examples in the Postman Client by clicking Save as Example button in the bottom right:

Step 2: Export your Collection

Postman supporting exporting collections as JSON (opens in a new tab). Use the v2.1 format.

Step 3: Install Optic

npm install -g @useoptic/optic

Then run the optic verify command. If you have an OpenAPI spec, point at it. If you do not have an OpenAPI spec, one will be created:

optic verify openapi.yml --postman collection.json

The first thing you will see is a list of undocumented API operations:

» Verifying API Behavior...
 
 [ Undocumented ]    get  /todos/{todoId}/status
 [ Undocumented ]  patch  /todos/{todoId}/status
 [ Undocumented ]   post  /todos/{todoId}
 [ Undocumented ]  patch  /user/profile/settings
 
 Document all new operations with $ optic update openapi.yaml --all
 Document individual operations with $ optic update openapi.yaml "[method] /[path]" ...

To document all the operations in my Postman Collection, run:

optic update openapi.yml --all --postman collection.json

Optic updated the OpenAPI spec with the 4 operations it observed in the example traffic, and the 3 shared components that are used across the API.

openapi: 3.1.0
info: ...
paths:
  /todos/{todoId}/status:
    get: ...
    patch: ...
  /todos/{todoId}:
    post: ...
  /user/profile/settings:
    patch: ...
components:
  schemas:
    TodoStatus: ...
    Todo: ...
    UserProfileSettings: ...

Step 4: Add to your OpenAPI description

What makes Optic different from every other Postman → OpenAPI generator is that you can use it over and over again. Optic does not regenerate your specification each time it runs, it patches the existing specification when the API changes. This means you can add description summary, additional schemas, change the $ref names, etc and Optic will never overwrite your work. It’s a true collaborator that does the tedious work of diffing your API behavior and updating the specification to match.

For example, if you add a task_url to example Todo schema and re-run the request in Postman, Optic detects this difference:

» Verifying API Behavior...
 
 
[ Diff ] 'task_url' is not documented
operation: get /todos/{todoId}/status
18 | application/json; charset=utf-8:
19 |   schema:
20 |     type: object
21 |     properties:  Undocumented 'task_url'
22 |       url:
23 |         type: string
24 |       time:
openapi.yml
fix schema by running $ optic update

When you run optic update openapi.yml --postman collection.json --all, Optic is smart enough to find the Todo component and update the spec in the right place. This will even work if the schema components are in different files. Optic makes the same patches to the specification a developer writing OpenAPI by hand would:

openapi: 3.1.0
info: ...
paths:
  /todos/{todoId}/status:
    get: ...
    patch: ...
  /todos/{todoId}:
    post: ...
  /user/profile/settings:
    patch: ...
components:
  schemas:
    TodoStatus: ...
    Todo:
        type: object
        properties:
          ...
          task_url:
            type: string
            example: https://notion.so/todo-list#anchor
    UserProfileSettings: ...

That's it! Now you can:

Client GuidesReverse Proxy