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,

• Installed Optic (opens in a new tab).
  • npm -g install @useoptic/optic, or sh -c "$(curl -Ls https://install.useoptic.com/install.sh)"
• Signed up for a Hoppscotch (opens in a new tab) account.
• Installed the Hoppscotch CLI, hopp (opens in a new tab).

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.

Export your API

Next, export your collection to download a JSON representation.

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"
}

Configure Optic to use the Hoppscotch CLI

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

capture:
  openapi.yml:
    server:
      # 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
    requests:
      run:
        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.