Generating OpenAPI with Hoppscotch and Optic

Nate Meyer 2023-10-18

Hoppscotch (opens in a new tab) is a popular alternative to Postman and is used by developers to build and test APIs. Collections of replayable API requests are great to have during development, but they are not a substitute for great API docs. This tutorial shows you how to use the Optic and Hoppscotch CLIs to generate and maintain accurate OpenAPI documentation from the data in your Hoppscotch collections (opens in a new tab).

Before we get started, this tutorial assumes that you have,

Define your API

In Hoppscotch, we’ve defined a few endpoints that our API uses. Note that we’ve used Hoppscotch’s environment variable syntax to reference a variable name URL.

Example of Hoppscotch POST

Example of Hoppscotch GET


At the time of writing, the format that Hoppscotch’s web app exports environments as is not the same format that the CLI requires. Later, we’ll create an environment file in the correct format for the CLI that defines URL.

Export your API

Next, export your collection to download a JSON representation.

Exporting from Hoppscotch

Once the file is downloaded, move it into your API application’s directory.

Create your environment file

When we defined our API endpoints earlier we used a variable, URL. Using a variable allows to supply different protocols and hostnames for different application environments or use cases. We’ll call ours optic.env.json. Create the file inside your application directory and give it the following contents,

  "URL": "http://localhost:8000"

Port 8000 is Optic Capture’s default proxy port. You can change the port by specifying a different value for optic capture's --proxy-port option. Traffic sent to the proxy will be analyzed and then forwarded to your application.

Configure Optic to use the Hoppscotch CLI

Inside your application directory, create an optic.yml file with contents similar to:

      # the command to start your application
      command: go run main.go
      # the url where your application is listening. Optic will forward requests
      # from the proxy to this URL.
      url: http://localhost:8080
        command: |
          hopp test --env=optic.env.json optic-example-collection.json

Run Optic Capture to generate an OpenAPI spec

Now that all the pieces are in place, all that’s left to do is run Optic Capture, optic capture openapi.yml --update interactive. Optic will create an OpenAPI specification named openapi.yml (you can give it a different name if you wish), and prompt you to confirm each endpoint it observes.

 optic capture openapi.yml --update interactive
Initializing OpenAPI file at openapi.yml
 Finished running requests
Learning path patterns for unmatched requests...
> /
 Is this the right pattern for GET /  yes
> /users
 Is this the right pattern for GET /users  yes
> /users/create
 Is this the right pattern for POST /users/create  yes
Documenting new operations:
 GET /
 POST /users/create
 GET /users

Take a look in the openapi.yml file and admire your OpenAPI spec!

Making Changes

Making changes is as simple as updating your app and/or Hoppscotch collection and rerunning Optic. Any new or changed endpoints will be added!

For example, if we add a department field for our users, Optic will update our OpenAPI spec when we run it again,

 optic capture openapi.yml --update interactive
 Finished running requests
 GET /
   200 response
 POST /users/create
   Request Body,  201 response
  [request body] 'department' has been added (/properties/department)
  [201 response body] 'department' has been added (/properties/department)
 GET /users
   200 response

Final Thoughts

Using Optic and Hoppscotch to generate and maintain accurate OpenAPI documentation is a great way to streamline your API development process. Optic makes it easy to take your existing Hoppscotch collections and implement them into a comprehensive documentation and verification flow.

Want to ship a better API?

Optic makes it easy to publish accurate API docs, avoid breaking changes, and improve the design of your APIs.

Try it for free