Generate OpenAPI from tests

Optic turns network traffic from your browser or your existing integration tests into an accurate OpenAPI documentation. Optic runs every time your code changes to update your OpenAPI spec or verify that it matches the implementation.

Capture traffic

Option 1: Capture traffic from your API

Optic starts a local proxy that 1) forwards traffic to an instance of your API and, 2) compares that traffic to your OpenAPI specification. You need to specify the server's address in the optic.yml under server.url. You also need to have your tests send requests through our proxy using the OPTIC_PROXY environment variable.

To start capturing your test traffic, run:

optic capture init /path/to/openapi.yml

The quickest way to explore Optic is to send mock requests defined in the optic.yml. We know this won't scale, but you can get it working right away and automate the traffic after you see how Optic works.

optic.yml

capture:
  openapi.yml:
    # 🔧 Runnable example with simple get requests. 
    # Run with "optic capture ${oasFile} --update interactive" 
    # You can change the server and the 'requests' section to experiment
    server:
      url: https://api.github.com
    requests:
      send: 
      - path: /users
        method: GET
      - path: /orgs/opticdev/repos
        method: GET   
      - path: /orgs/facebook/repos
        method: GET   
      - path: /orgs/github/repos
        method: GET

In this example, Optic will send requests to https://api.github.com and make GET requests to /users and some /orgs/{orgId}/repos. You can change this to run against your API server and pass in a command to start a local server. A full configuration reference can be viewed here.

optic capture openapi.yml --update=interactive

Option 2: Import a Postman collection

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

optic capture openapi.yml --postman collection.json --update=interactive

Documenting your endpoints

Optic uses real traffic to update API endpoints. You will be asked to approve each path before Optic adds it to your OpenAPI specification. It can usually infer complex paths like /user/{userId}/orders/{orderId}, but if it gets something wrong you can manually correct it during the interactive flow. You only have to do this once. The more Optic learns about your URL schema the better it gets.

⚠️

Are some of the paths Optic observed not part of your API? Ie. Images, html, etc? Just add an extension to your OpenAPI file to tell Optic to ignore these paths going forward:

openapi: 3.1.0
x-optic-path-ignore:
  - "**/*.+(ico|png|jpeg|jpg|gif)"
  - "/health-check"

After approving a few of the new operations Optic observed we can see that it wrote a lot of OpenAPI for us:

Learning path patterns for unmatched requests...
Documenting new operations:
✔ GET /users
✔ GET /orgs/{orgId}/repos

+ 1384 - 0 openapi.yml

Keeping your spec up to date

Now that you have an OpenAPI spec, the challenge is keeping it up to date. Since we already have requests or tests set up, we can verify that the OpenAPI spec matches the traffic it receives (think of this like a snapshot test for your API).

Update your OpenAPI based on traffic by running:

optic capture openapi.yml --update

Run in CI

alt

Calling optic run in your CI pipeline runs optic capture on every OpenAPI specification with a capture config in the optic.yml file. It also runs breaking change checks and other API standards your team has configured and reports on the state of all the API changes being proposed.

Next: Set up Optic in CI

Diff OpenAPI Versions Capturing Test Traffic