Table of contents

  1. Overview
  2. Run api init
  3. Configure api start task
  4. Give Optic the ability to start your API on a port it controls
    1. Spring Supported No Code Changes
  5. Run api check to verify integration


By observing your API traffic, Optic learns the API contract, detects whenever the API’s behavior changes, and helps you test the API.

The goal of this tutorial is help you configure the Optic CLI to start your API and monitor the traffic from your Java development environment. Once complete, you’ll invoke your application directly with Optic’s api command.

# your original start command
java application
# is substituted for Optic's start command
api start

Run api init

First, open a terminal and navigate to an API project. Your project will need to be runnable from this directory without any special permissions. Then run:

api init

alt text

After running api init Optic will add an optic.yml which:

Note The optic.yml file and the .optic folder should both be checked into version control.

Configure api start task

Now it’s time to show Optic how to start your API. Once completed you’ll be able to run your API using Optic’s api start command.

Open the optic.yml file in your favorite text editor and change the command and baseUrl fields:

name: Demo API
    command: java application
    baseUrl: http://localhost:4000

command - the command used to start your API server. It MUST:

  • Start a long-running process (your API) that stays running until exited
  • Be runnable from the same directory as the optic.yml file w/o any special permissions

baseUrl - the URL where you want the API to be accessible locally. It MUST:

  • Be on a port/hostname that doesn’t require special permissions to bind to (e.g. port 1024 and up) It SHOULD:
  • Be the same URL you use for local development today, that way the API consumers don’t need to be updated.

Give Optic the ability to start your API on a port it controls

Now you need to update your start command or code so that your API starts on the port Optic assigns it via the OPTIC_API_PORT environment variable.

This usually requires one of the following:

  • Updating 1-3 lines of code in your project
  • A flag to be passed into your start command that sets the API port to OPTIC_API_PORT

Look below for examples of how to make this change in your API framework:

Spring Supported No Code Changes

If you use ./gradlew bootRun to run your spring app, you just have to update your start command in your optic.yml file:


  command: ./gradlew bootRun


  command:  export SERVER_PORT=$OPTIC_API_PORT ; ./gradlew bootRun

Note: If you use maven to run your app, the same approach will work. Just make sure your optic.yml includes export SERVER_PORT=$OPTIC_API_PORT ; so that the port that maven uses is the OPTIC_API_PORT.

Now when Optic runs your start command, your API will start on the port Optic assigns it.

Run api check to verify integration

Now it’s time to test that you have set up Optic correctly. The Optic CLI has a check command for testing the integration one step at a time to help diagnose any problems.

Here’s an example of running api check start with a working integration:

alt text

Now run the command in your project:

api check start

If Optic detects any issues with your API, it will provide a link to a fix in our documentation.

Need more help? Schedule some time to meet the maintainers and dig into your setup, or search GitHub Issues for your error, and open a new issue if nothing relevant returns.

All Done! Nice Work

Now that Optic is integrated, it’s time to document your API.

Start Documenting