Other frameworks

Optic still works even if your framework isn't listed here, all that you need is an OpenAPI file to get started. Some of the ways you can get an OpenAPI spec are:

Writing an OpenAPI spec manually
Looking at your framework's ecosystem to find OpenAPI spec generators from code
Using Optic to create a specification from traffic

We'll be exploring how to create an OpenAPI specification from traffic using integration tests. This is a great way to make sure your docs match the API implementation.

In this guide, we'll be writing a script to capture traffic from our server that we can use to generate an OpenAPI spec, which we can then connect up to CI. For this, we will need:

optic installed locally
A command to run your web server locally
A command to run integration tests against your web server

Starting your web server

ℹ️

Optic works against http traffic, meaning that your tests need to make local http requests. This is why we're initializing a server

First off, we'll need a command that starts your local web server, along with any other dependencies it may need (like a database). For this guide, we'll say that we have a command that we can run start-server.

$ start-server
> server is running on localhost:3000

ℹ️

You may want a set up script that also runs migrations + seeds your database if you expect to run this against fresh instances (e.g. like in CI).

Writing integration tests

Firstly, we'll want to write our integration tests (if we don't have any already). You'll need to be able to inject the port you make requests to since Optic acts as a reverse proxy to capture traffic.

In this example we're going to be using writing our tests in Javascript (using supertest), but you can use any framework or testing tool as long as requests are made through http (e.g. curl, Postman, or a custom script).

const { app } = require("./app");
const request = require("supertest");
 
// This environment variable is injected when running `optic capture --reverse-proxy --command`
const opticHost = process.env.OPTIC_HOST;
 
let agent;
 
beforeAll(() => {
  agent = request.agent(opticHost || app);
});
 
describe("GET /users", () => {
  it("returns the list of users", async () => {
    const response = await agent.get(`/users`);
    expect(response.status).toBe(200);
    const body = await response.json();
 
    expect(body.length).toBe(1);
  });
});
 
describe("POST /users", () => {
  it("creates a user", async () => {
    const response = await agent
      .post(`/users`)
      .send({ name: "my name" });
    expect(response.status).toBe(201);
    const body = await response.json();
    expect(body.id).toBeTruthy();
  });
});

ℹ️

In this example, we're looking for the environment variable OPTIC_HOST which will send requests to the Optic reverse proxy host, instead of the default test setup. This way, our tests run both with and without Optic.

Connecting Optic

Now that you have integration tests you can run, you can configure Optic to run these scripts

# creates an openapi file
optic new openapi.yml
 
# Starts the web server - the trailing & runs the webserver command in the background
# You can see the backgrounded processes by running `jobs -l`
# fg or fg %{job_id} to switch to this process or kill -9 {job_id} to kill the process
start-server &
> server is running on localhost:3000
 
# Set up capture
# `yarn run test:integration` is our test command - substitute this with your own test command
optic capture openapi.yml http://localhost:3000 --reverse-proxy --command "yarn run test:integration"
 
## Updates spec with captured traffic
optic update openapi.yml --all

Running this script will generate an OpenAPI spec that matches the traffic that was sent during your tests.

Connecting to CI

Now that you can generate an OpenAPI specification from your tests, you can connect Optic in CI to to check for breaking changes and always keep your documentation in sync. Follow our CI setup guides (GitHub or GitLab).

You can run this in CI in two different ways:

manually run the above steps to update your OpenAPI spec (follow the regular steps)
automatically update the OpenAPI spec when your tests traffic changes (follow the generated spec steps, and use the above steps as your generation script)

Express Lint OpenAPI