OpenAPI and Go with Optic
To begin using Optic with your API you first need an OpenAPI file describing your API. This YAML or JSON file can be written by hand or generated from your code. This document describes the recommended process for generating a new OpenAPI file for a Go project written with any framework or HTTP package.
For APIs written in Go, we recommend using Optic's capture proxy via the
optic capture command.
To demonstrate, we've set up a simple example available here (opens in a new tab). Our example uses gin-gonic/gin (opens in a new tab) for the http framework but the content here is equally applicable to the standard library's
net/http package or other frameworks. The steps below are written for our example repo but should be easy to adapt to your own.
All commands below are assumed to be run from the directory containing the
Start the application locally,
go run main.go,
$ go run main.go ... [GIN-debug] Listening and serving HTTP on :8080
In a new terminal window, start the Optic proxy,
optic capture --reverse-proxy ./openapi.yml http://localhost:8080. This starts the Optic proxy in reverse-proxy mode, where it will accept requests on
localhost:8000 and forward them to the URL provided in the command (in this case
$ optic capture --reverse-proxy openapi.yml http://localhost:8080 Proxy URL: https://localhost:8000 (send traffic here) Forwarding URL: http://localhost:8080 (traffic will be forwarded here) help Press [ Enter ] to finish capturing requests
With the proxy running, we can now make requests and have Optic capture them. In another new terminal window, make some curl requests,
$ curl http://localhost:8000/users
You should see your proxy window update with "1 requests captured".
If you don't see Optic capturing any traffic, make sure you're sending requests to the proxy (
localhost:8000) and not the application directly.
You can now stop the proxy with either
ctrl-c. The proxy output should look similar to,
$ optic capture --reverse-proxy openapi.yml http://localhost:8080 Initializing OpenAPI file at openapi.yml Proxy URL: https://localhost:8000 (send traffic here) Forwarding URL: http://localhost:8080 (traffic will be forwarded here) help Press [ Enter ] to finish capturing requests ✔ 1 requests captured » Verifying API behavior with traffic from last 1 capture. Reset captures $ optic capture clear openapi.yml` Undocumented GET /users /users Document all new operations with $ optic update openapi.yml --all Document individual operations with $ optic update openapi.yml "[method] /[path]" ...
Now that Optic has captured a request, we can document that in an OpenAPI file. Run
optic update openapi.yml --all to write all the captured requests to
$ optic update openapi.yml --all » Documenting new operations... added get /users » Updating operations... Share a link to documentation with your team (optic api add openapi.yml)
Take a look at
$ cat openapi.yml info: title: Untitled service version: 1.0.0 openapi: 3.1.0 paths: /users: get: responses: "200": description: 200 response content: application/json; charset=utf-8: schema: $ref: "#/components/schemas/GetUsers200ResponseBody" components: schemas: GetUsers200ResponseBody: type: array items: type: object properties: id: type: number name: type: string required: - id - name
We've generated an OpenAPI file from traffic!
From here you can edit your openapi.yml file (maybe to set the
title field), run more capture sessions, etc. Optic will update the OpenAPI file as new requests are captured, adding or modifying endpoints as necessary.
Don't forget to check your
openapi.yml file into source control. Optic can use it to verify your code matches your OpenAPI spec and prevent breaking changes!
Automate your OpenAPI generation and test your API specifications by setting up Optic in CI.