tinspec-openapi

README

tinspec-openapi

Generate an OpenAPI 3.1 spec from a Go web service by static analysis — no annotations, no code generation, and no running server required. It understands net/http, chi, gin, echo, and fiber, including generics, response envelopes ({data, error}), maps, and well-known types (uuid.UUID, time.Time, …).

It extracts path/query/header/cookie parameters (typed and required from struct binds), JSON and form / multipart request bodies (incl. file uploads), non-JSON (e.g. text/plain) responses and response headers, and security schemes — HTTP bearer/basic, API keys, and OAuth2 (from an oauth2.Config), including auth applied via router middleware.

Optionally it can serve the spec, watch your code, and learn the real request/response shapes by proxying live traffic.

Install

Homebrew (macOS / Linux)

brew tap tinspec/tap https://gitlab.com/tinspec/homebrew-tap.git
brew install tinspec-openapi

Shell script

curl -fsSL https://gitlab.com/tinspec/tinspec-openapi/-/raw/main/install.sh | sh

Installs into /usr/local/bin (override with INSTALL_DIR=$HOME/.local/bin).

Linux packages

Download the .deb, .rpm, or .apk for your arch from the releases page, then:

sudo dpkg -i tinspec-openapi_*_amd64.deb     # Debian/Ubuntu
sudo rpm -i  tinspec-openapi_*_amd64.rpm      # Fedora/RHEL
sudo apk add --allow-untrusted tinspec-openapi_*_amd64.apk  # Alpine

Docker

docker run --rm -v "$PWD":/src registry.gitlab.com/tinspec/tinspec-openapi \
  gen --dir /src

go install

go install gitlab.com/tinspec/tinspec-openapi/cmd/tinspec-openapi@latest

The binary is tinspec-openapi; Homebrew and the install script also add a short tio alias.

Usage

# Generate a spec to stdout (or a file with --out)
tinspec-openapi gen --dir .

# Generate and keep it up to date as you code
tinspec-openapi gen --dir . --watch --out openapi.json

# Serve the spec at http://localhost:4000/openapi.json
tinspec-openapi serve --dir . --watch

Learn from live traffic

Run your backend, then put the tool in front of it. It serves the static spec at /openapi.json, transparently proxies everything else to your backend, and refines the spec from the real bodies it sees:

tinspec-openapi serve --dir . --watch \
  --learn --learn-target http://localhost:8080

Send your app's traffic to http://localhost:4000; what it learns is written to openapi.overlay.json and merged into the served spec live.

Run tinspec-openapi help (or help gen / help serve) for all flags.

Development

This is a Go monorepo. The CLI and its libraries (spec, analyzer) live in the root module; conformance/, tests/, and examples/ are separate dev-only modules so the released CLI never pulls web-framework dependencies.

make build        # build ./bin/tinspec-openapi
make test         # test all modules
make conformance  # run the WPT-style conformance suite
make install      # install to GOBIN (+ tio alias)

A local go.work (gitignored) ties the modules together for development; make targets work with or without it.

License

Apache-2.0.