Generate OpenAPI

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

• Capture traffic directly from your API
• Import a Postman collection

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

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

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.

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

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. Learn more about running in CI here