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
, orsh -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
.
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.
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:
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.
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