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.

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 localhost:8080).

$ 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".

You can now stop the proxy with either Enter or 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 ./openapi.yml.

$ 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 ./openapi.yml,

$ 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.

What's next

Automate your OpenAPI generation and test your API specifications by setting up Optic in CI.